Invoice – Capture

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.

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 The Capture Request

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

Request

1
2
3
4

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

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

{
    "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
          }
        ]
  }
}

Show fields

Required	Parameter name	Datatype	Value (with description)
︎	`transaction.activity`	`string`	FinancingConsumer.
︎	`transaction.Amount`	`integer`	Amount entered in the lowest momentary units of the selected currency. E.g. `10000` = `100.00 SEK`, `5000` = `50.00 SEK`.
︎	`transaction.vatAmount`	`integer`	Amount entered in the lowest momentary units of the selected currency. E.g. `10000` = `100.00 SEK`, `5000` = `50.00 SEK`.
︎	`transaction.payeeReference`	`string`	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`.
︎	`transaction.description`	`string`	A textual description of the capture
︎	`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`.
︎	`itemDescriptions.description`	`string`	A textual description of this product
︎	`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`.
︎	`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`.
︎	`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.

Capture Response

Response

1
2
3

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.1/3.0/2.0
api-supported-versions: 3.1/3.0/2.0

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

{
    "paymentorder": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "capture": {
        "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "itemDescriptions": {
            "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
        },
        "transaction": {
            "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/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": "ABC123", 
            "receiptReference": "ABC123", 
            "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/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                    "rel": "edit-capture",
                    "method": "PATCH"
                }
            ]
        }
    }
}

Show fields

Field	Type	Description
`paymentOrder`	`string`	The relative URL and unique identifier of the `payment` resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
`id`	`string`	The relative URL and unique identifier of the `capture` resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
`itemDescriptions`	`object`	The object representation of the `itemDescriptions` resource.
`id`	`string`	The relative URL and unique identifier of the `itemDescriptions` resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
`transaction`	`object`	The object representation of the generic `transaction` resource, containing information about the current transaction.
`id`	`string`	The relative URL and unique identifier of the `transaction` resource . Please read about URL Usage to understand how this and other URLs 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` or `failed`. If a partial capture has been done and further transactions are possible, the state will be `awaitingActivity`.
`number`	`integer`	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. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the `transaction.number` or the `payeeReference` is sent to the acquirer. If Swedbank Pay handles the settlement, the `transaction.number` is sent and the `payeeReference` must be in the format of `A-Za-z0-9` and `string(30)`. If you handle the settlement, Swedbank Pay will send the `payeeReference` and it will be limited to the format of `string(12)`. All characters must be digits. In Invoice Payments `payeeReference` is used as an invoice/receipt number, if the `receiptReference` is not defined.
`receiptReference`	`string`	A unique reference to the transaction, provided by the merchant. Can be used as an invoice or receipt number as a supplement to `payeeReference`.
`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.

GET Capture Request

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

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

{
    "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
          }
        ]
  }
}

GET Capture Response

Response

1
2

HTTP/1.1 200 OK
Content-Type: application/json

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

{
    "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