Two-phase payments: When dealing in physical goods using two-phase payment methods, 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 methods, 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
}
]
}
}
| 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 |
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.
Capture Response
Response
1
2
3
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.x/2.0
api-supported-versions: 3.x/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"
}
]
}
}
}
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.
authorization
object
id
string
The relative URL and unique identifier of the authorization resource this captures belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.
itemDescriptions
object
itemDescriptions resource.
id
string
The relative URL and unique identifier of the itemDescriptions resource this captures belongs to. 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 this captures belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.
created
string
updated
string
type
string
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 textual description of the purchase. Maximum length is 40 characters.
payeeReference
string(30)
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 to the acquirer 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
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
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