Checkout v2

Capture

schedule 5 min read

Capturing the authorized funds.

Edit "Capture" on GitHub

Step 5: Capture the funds

Captures are only possible when a payment has a successful authorize transaction, naturally excluding one-phase payment instruments like Swish and Trustly. Two-phase payment instruments like Card and Vipps however, require a Capture to be completed. Please note that Invoice captures differ from the others. These are explained in it’s own section.

In addition to full captures, it is possible to do partial captures 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. Useful for when you have to split orders into several shipments, for instance.

First off, you must request the order information from the server to get the request link. With this, you can request the capture with the amount to capture, and get the status back.

sequenceDiagram
    participant Merchant
    participant SwedbankPay as Swedbank Pay

    rect rgba(81,43,43,0.1)
        activate Merchant
        note left of Payer: Capture
        Merchant ->>+ SwedbankPay: rel:create-paymentorder-capture
        deactivate Merchant
        SwedbankPay -->>- Merchant: Capture status
        note right of Merchant: Capture here only if the purchased<br/>goods don't require shipping.<br/>If shipping is required, perform capture<br/>after the goods have shipped.<br>Should only be used for <br>Payment Instruments that support <br>Authorizations.
    end

To capture the authorized payment, we need to perform create-paymentorder-capture against the accompanying href returned in the operations list. See the abbreviated request and response below:

Request

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
42
43
44
45
46
POST /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/captures HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "transaction": {
        "description": "Capturing the authorized payment",
        "amount": 1500,
        "vatAmount": 375,
        "payeeReference": "AB832",
        "receiptReference": "AB831",
        "orderItems": [
            {
                "reference": "P1",
                "name": "Product1",
                "type": "PRODUCT",
                "class": "ProductGroup1",
                "itemUrl": "https://example.com/products/123",
                "imageUrl": "https://example.com/product123.jpg",
                "description": "Product 1 description",
                "discountDescription": "Volume discount",
                "quantity": 4,
                "quantityUnit": "pcs",
                "unitPrice": 300,
                "discountPrice": 200,
                "vatPercent": 2500,
                "amount": 1000,
                "vatAmount": 250
            },
            {
                "reference": "P2",
                "name": "Product2",
                "type": "PRODUCT",
                "class": "ProductGroup1",
                "description": "Product 2 description",
                "quantity": 1,
                "quantityUnit": "pcs",
                "unitPrice": 500,
                "vatPercent": 2500,
                "amount": 500,
                "vatAmount": 125
            }
        ]
    }
}
Required Field Type Description
check transaction object The transaction object.
check └➔ description string The description of the capture transaction.
check └➔ amount integer The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.
check └➔ 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 of the total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.
check └➔ payeeReference string(30) 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(30) A unique reference from the merchant system. It is used to supplement payeeReference as an additional receipt number.
check └➔ orderItems array The array of items being purchased with the order. Used to print on invoices if the payer chooses to pay with invoice, among other things. orderItems is required in all requests. In capture requests it should only contain the items to be captured from the order.
check └─➔ reference string A reference that identifies the order item.
check └─➔ name string The name of the order item.
check └─➔ type enum PRODUCT, SERVICE, SHIPPING_FEE, PAYMENT_FEE, DISCOUNT, VALUE_CODE or OTHER. The type of the order item.
check └─➔ class string The classification of the order item. Can be used for assigning the order item to a specific product category, such as MobilePhone. Note that class cannot contain spaces and must follow the regex pattern [\w-]*. Swedbank Pay may use this field for statistics.
  └─➔ itemUrl string The URL to a page that can display the purchased item, product or similar.
︎︎︎ └─➔ imageUrl string The URL to an image of the order item.
  └─➔ description string The human readable description of the order item.
  └─➔ discountDescription string The human readable description of the possible discount.
check └─➔ quantity integer The 4 decimal precision quantity of order items being purchased.
check └─➔ quantityUnit string The unit of the quantity, such as pcs, grams, or similar. This is used for your own book keeping.
check └─➔ unitPrice integer The price per unit of order item, including VAT.
  └─➔ discountPrice integer If the order item is purchased at a discounted price. This field should contain that price, including VAT.
check └─➔ vatPercent integer The percent value of the VAT multiplied by 100, so 25% becomes 2500.
check └─➔ amount integer The total amount including VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 SEK and 5000 equals 50.00 SEK.
check └─➔ vatAmount integer The total amount of VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 SEK and 5000 equals 50.00 SEK.
check └─➔ reference string A reference that identifies the order item.
check └─➔ name string The name of the order item.
check └─➔ type enum PRODUCT, SERVICE, SHIPPING_FEE, PAYMENT_FEE, DISCOUNT, VALUE_CODE or OTHER. The type of the order item.
check └─➔ class string The classification of the order item. Can be used for assigning the order item to a specific product category, such as MobilePhone. Note that class cannot contain spaces and must follow the regex pattern [\w-]*. Swedbank Pay may use this field for statistics.
︎︎︎ └─➔ itemUrl string The URL to a page that can display the purchased item, such as a product page
︎︎︎ └─➔ imageUrl string The URL to an image of the order item.
︎︎︎ └─➔ description string The human readable description of the order item.
︎︎︎ └─➔ discountDescription string The human readable description of the possible discount.
check └─➔ quantity decimal The 4 decimal precision quantity of order items being purchased.
check └─➔ quantityUnit string The unit of the quantity, such as pcs, grams, or similar.
check └─➔ unitPrice integer The price per unit of order item, including VAT.
︎︎︎ └─➔ discountPrice integer If the order item is purchased at a discounted price. This field should contain that price, including VAT.
check └─➔ vatPercent integer The percent value of the VAT multiplied by 100, so 25% becomes 2500.
check └─➔ amount integer The total amount including VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
check └─➔ vatAmount integer The total amount of VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.

If the capture succeeds, it should respond with something like the following:

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "capture": {
        "id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "transaction": {
            "id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "type": "Capture",
            "state": "Completed",
            "amount": 15610,
            "vatAmount": 3122,
            "description": "Capturing the authorized payment",
            "payeeReference": "AB832",
            "receiptReference": "AB831"
        }
    }
}
Property Type Description
payment string The relative URI of the payment this capture transaction belongs to.
capture object The capture object, containing the information about the capture transaction.
└➔ id string The relative URI of the created capture transaction.
└➔ transaction object The transaction object, containing information about the current transaction.
└─➔ id string The relative URI of the current transaction resource.
└─➔ 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 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 transaction amount (including VAT, if any) 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 of the 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(30) A unique reference from the merchant system. It is set per operation to ensure an exactly-once delivery of a transactional operation. It is used to supplement payeeReference as an additional receipt number.

Invoice

Unlike the other payment instruments, performing an invoice capture won’t move any funds in itself. It will generate the actual invoice and distribute it to the payer.

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 checkout/v2 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
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": "/psp/checkout/v2/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "capture": {
        "id": "/psp/checkout/v2/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "itemDescriptions": {
            "id": "/psp/checkout/v2/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
        },
        "transaction": {
            "id": "/psp/checkout/v2/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", 
            "isOperational": false,
            "problem": {
                "type": "https://api.payex.com/psp/errordetail/checkout/v2/3DSECUREERROR",
                "title": "Error when complete authorization",
                "status": 400,
                "detail": "Unable to complete 3DSecure verification!",
                "problems": [
                ] 
            "operations": [
                {
                    "href": "/psp/checkout/v2/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 transaction amount (including VAT, if any) 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 of the 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

sequenceDiagram
  participant SwedbankPay as Swedbank Pay

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