Invoice

Capture

schedule 5 min read
warning

Two-phase payments

When dealing in physical goods using two-phase payment instruments, all goods must be shipped before you capture the authorized amount. This is regulated in part by the Swedish Distance and Doorstep Sales Act, required in our terms and (for card payments) required by Visa and Mastercard.

Capture

The final step in the integration process for Invoice Redirect, Seamless View and Direct is to complete a Capture.

An invoice capture will generate the invoice and distribute it to the payer. This differs from i.e. Card Payments, where a capture operation will fully or partially charge the payer’s authorized amount.

Step 1: Create FinancingConsumer Capture

To capture a FinancingConsumer invoice payment, perform the create-capture operation with the following request body:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
POST /psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "transaction": {
        "activity": "FinancingConsumer",
        "amount": 13500,
        "vatAmount": 2500,
        "payeeReference": "ABC856",
        "receiptReference": "ABC855",
        "description": "description for transaction",
        "itemDescriptions": [
          {
            "amount": 12500,
            "description": "item description 1"
          },
          {
            "amount": 1000,
            "description": "item description 2"
          }
        ],
        "vatSummary": [
          {
            "amount": 12500,
            "vatPercent": 2500,
            "vatAmount": 2500
          },
          {
            "amount": 1000,
            "vatPercent": 0,
            "vatAmount": 0
          }
        ]
  }
}
Required Parameter name Datatype Value (with description)
check transaction.activity string FinancingConsumer.
check transaction.Amount integer Amount entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 SEK, 5000 = 50.00 SEK.
check transaction.vatAmount integer Amount entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 SEK, 5000 = 50.00 SEK.
check transaction.payeeReference string(50) The payeeReference is the receipt/invoice number if receiptReference is not defined, which is a unique reference with max 50 characters set by the merchant system. This must be unique for each operation and must follow the regex pattern [\w-]*.
  transaction.receiptReference string(50) The receiptReference is a reference from the merchant system. This reference is used as an invoice/receipt number to supplement payeeReference.
check transaction.description string A textual description of the capture
check itemDescriptions.amount integer Total price for this order line - entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 SEK, 5000 = 50.00 SEK.
check itemDescriptions.description string A textual description of this product
check vatSummary.amount integer Total price for this order line - entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 SEK, 5000 = 50.00 SEK.
check vatSummary.vatAmount integer VAT Amount entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 SEK, 5000 =50.00 SEK.
check vatSummary.vatPercent integer The percent value of the VAT multiplied by 100. Supported values : 0, 600, 800, 1000, 1200, 1400, 1500, 2200, 2400, 2500.

Notes on FinancingConsumer captures:

  • The due date is set by Swedbank Pay based on the agreement with merchant. Standard due date is 14 days.
  • The invoice number is set by Swedbank Pay.

The created capture resource contains information about the capture transaction made against a invoice payment.

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "capture": {
        "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "itemDescriptions": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
        },
        "transaction": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "created": "2016-09-14T01:01:01.01Z",
            "updated": "2016-09-14T01:01:01.03Z",
            "type": "Capture",
            "state": "Completed",
            "number": 1234567890,
            "amount": 1000,
            "vatAmount": 250,
            "description": "Test transaction",
            "payeeReference": "AH123456", 
            "receiptReference": "AH12355", 
            "isOperational": false,
            "problem": {
                "type": "https://api.payex.com/psp/errordetail/invoice/3DSECUREERROR",
                "title": "Error when complete authorization",
                "status": 400,
                "detail": "Unable to complete 3DSecure verification!",
                "problems": [
                ] 
            "operations": [
                {
                    "href": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                    "rel": "edit-capture",
                    "method": "PATCH"
                }
            ]
        }
    }
}

Field Type Description  
payment string The relative URI and unique identifier of the payment resource this capture belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.  
capture string The current capture transaction resource.  
└➔ id string The relative URI and unique identifier of the capture resource this capture belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.  
└➔ itemDescriptions object The object representation of the itemDescriptions resource.  
└─➔ id string The relative URI and unique identifier of the itemDescriptions resource this capture belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.  
└➔ transaction object The object representation of the generic transaction resource.  
└─➔ id string The relative URI and unique identifier of the transaction resource this capture belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution.  
└─➔ created string The ISO-8601 date and time of when the transaction was created.  
└─➔ updated string The ISO-8601 date and time of when the transaction was updated.  
└─➔ type string Indicates the transaction type.  
└─➔ state string Indicates the state of the transaction, usually initialized, completed orfailed. If a partial capture has been done and further transactionsare possible, the state will be awaitingActivity.  
└─➔ number string The transaction number, useful when there’s need to reference the transaction in human communication. Not usable for programmatic identification of the transaction, where id should be used instead.  
└─➔ amount integer The amount (including VAT, if any) to charge the payer, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.  
└─➔ vatAmount integer The payment’s VAT (Value Added Tax) amount, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The vatAmount entered will not affect the amount shown on the payment page, which only shows the total amount. This field is used to specify how much ofthe total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.  
└─➔ description string A 40 character length textual description of the purchase.  
└─➔ payeeReference string A unique reference from the merchant system. It is set per operation to ensure an exactly-once delivery of a transactional operation. See payeeReference for details.In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.  
└─➔ receiptReference string A unique reference for the transaction. This reference is used as an invoice/receipt number.  
└─➔ failedReason string The human readable explanation of why the payment failed.  
└─➔ isOperational bool true if the transaction is operational; otherwise false.  
└─➔ operations array The array of operations that are possible to perform on the transaction in its current state.  

Step 2: Inspecting the Captures

The captures resource lists the capture transactions performed on a specific invoice payment.

Request

1
2
3
4
GET /psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "captures": [{
        "itemDescriptions": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/7e6cdfc3-1276-44e9-9992-7cf4419750e1/itemdescriptions"
        },
        "receiptReference": "ABC855",
        "invoiceCopy": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures/7e6cdfc3-1276-44e9-9992-7cf4419750e1/invoicecopy",
        "transaction": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "created": "2016-09-14T01:01:01.01Z",
            "updated": "2016-09-14T01:01:01.03Z",
            "type": "Capture",
            "state": "Failed",
            "number": 1234567890,
            "amount": 1000,
            "vatAmount": 250,
            "description": "Test transaction",
            "payeeReference": "AH123456",
            "failedReason": "",
            "isOperational": false,
            "operations": []
        }
    }]
}

Capture Flow

A capture can only be performed on a successfully authorized transaction. It is possible to do a partial capture where you only capture a part of the authorized amount. You can do other captures on the same payment later, up to the total authorized amount.

sequenceDiagram
  participant SwedbankPay as Swedbank Pay

  Merchant->>SwedbankPay: Post <Invoice captures>
  activate Merchant
  activate SwedbankPay
  SwedbankPay-->>Merchant: transaction resource
  deactivate Merchant
  deactivate SwedbankPay