Invoice – Capture

Capture

The capture transaction is where you ensure that the funds are charged from the payer. This step usually takes place when the product has exchanged possession. You must first do a GET request on the payment to find the create-capture operation.

Please note that you have a maximum of 5 consecutive failed attempts at a capture. The payment will be locked after this, and you need to contact us for another attempt.

Create Capture Transaction

To create a capture transaction to withdraw money from the payer’s card, you need to perform the create-capture operation.

Capture Request

Request

1
2
3
4

POST /psp//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

{
    "transaction": {
        "amount": 1500,
        "vatAmount": 250,
        "description": "Test Capture",
        "payeeReference": "ABC123"
    }
}

Field	Type	Description
`transaction`	`object`	The object representation of the generic `transaction` resource, containing information about the current transaction.
`amount`	`integer`	Amount Entered in the lowest momentary units of the selected currency. E.g. 10000 100.00 NOK, 5000 50.00 SEK.
`vatAmount`	`integer`	Amount Entered in the lowest momentary units of the selected currency. E.g. 10000 100.00 NOK, 5000 50.00 SEK.
`description`	`string`	A textual description of the capture transaction.
`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.

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

{
    "payment": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "capture": {
        "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "transaction": {
            "id": "/psp//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": 1500,
            "vatAmount": 250,
            "description": "Test Capture",
            "payeeReference": "ABC123",
            "isOperational": false,
            "operations": []
        }
    }
}

Show fields

Property	Type	Description
`payment`	`string`	The relative URL of the payment this `capture` transaction belongs to.
`capture`	`object`	The `capture` resource contains information about the `capture` transaction made against a card payment.
`id`	`string`	The relative URL of the created `capture` transaction.
`transaction`	`object`	The object representation of the generic `transaction` resource, containing information about the current transaction.
`id`	`string`	The relative URL 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` or `failed`. If a partial 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`	Amount is entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
`vatAmount`	`integer`	If the amount given includes VAT, this may be displayed for the user in the payment page (redirect only). Set to 0 (zero) if this is not relevant.
`description`	`string`	A human readable description of maximum 40 characters of the transaction
`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.
`failedReason`	`string`	The human readable explanation of why the payment failed.
`isOperational`	`boolean`	`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.

List Capture Transactions

The captures resource list the capture transactions (one or more) on a specific payment.

Request

1
2
3
4

GET /psp//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

{
    "transaction": {
        "amount": 1500,
        "vatAmount": 250,
        "description": "Test Capture",
        "payeeReference": "ABC123"
    }
}

The capture resource contains information about the capture transaction made against a invoice payment. You can return a specific capture transaction by performing a GET request towards the specific transaction’s id.

Transaction List 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

{
    "paymentorder": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "captures": { 
        "receiptReference": "AH12355", 
        "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment",
        "captureList": [{
            "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "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": "AH123456",
                "isOperational": false,
                "operations": []
            }
        }]
    }
}

Show fields

Field	Type	Required
`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 `captures` resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
`{{ transaction }}List`	`array`	The array of capture transaction objects.
`{{ transaction }}List[]`	`object`	The capture transaction object described in the `capture` resource below.
`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`.
`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.

Capture Sequence Diagram

Capture can only be done on an authorized transaction. It is possible to do a partial capture where you only capture a part of the authorized amount. You can do more captures on the same payment up to the total authorization amount later.

sequenceDiagram
  activate Merchant
  Merchant->>-SwedbankPay: POST [ captures]
  activate SwedbankPay
  SwedbankPay-->>-Merchant: transaction resource