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 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.
Create capture transaction
To create a capture
transaction to withdraw money from the payer’s card, you
need to perform the create-capture
operation.
Request
1
2
3
4
5
6
7
8
9
10
11
12
13
POST /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"transaction": {
"amount": 1500,
"vatAmount": 250,
"description": "Test Capture",
"payeeReference": "ABC123"
}
}
Required | Field | Type | Description |
---|---|---|---|
check | transaction |
object |
The object representation of the generic transaction resource. |
check | └➔ amount
|
integer |
Amount Entered in the lowest momentary units of the selected currency. E.g. 10000 100.00 NOK, 5000 50.00 SEK. |
check | └➔ vatAmount
|
integer |
Amount Entered in the lowest momentary units of the selected currency. E.g. 10000 100.00 NOK, 5000 50.00 SEK. |
check | └➔ description
|
string |
A textual description of the capture transaction. |
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. |
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"capture": {
"id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"transaction": {
"id": "/psp/creditcard/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": []
}
}
}
Property | Type | Description |
---|---|---|
payment |
string |
The relative URI 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 URI of the created capture transaction. |
└➔ transaction
|
object |
The object representation of the generic transaction resource . |
└─➔ 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 |
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. It is set per operation to ensure an exactly-once delivery of a transactional operation. See payeeReference for details. |
└─➔ 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. |
The captures
resource list the capture transactions (one or more) on a
specific payment.
Request
1
2
3
4
GET /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
The capture
resource contains information about the
capture
transaction made against a creditcard payment. You can
return a specific capture
transaction by performing a GET
request
towards the specific transaction’s id
.
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
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"captures": {
"id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures",
"captureList": [{
"id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"transaction": {
"id": "/psp/creditcard/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,
"operations": []
}
}]
}
}
Field | Type | Required |
---|---|---|
payment |
string |
The relative URI and unique identifier of the payment resource this captures belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
captures |
object |
The current captures resource. |
└➔ id
|
string |
The relative URI and unique identifier of the captures resource this captures belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ captureList
|
array |
The array of capture transaction objects. |
└➔ captureList[]
|
object |
The capture transaction object described in the capture resource below. |
└─➔ id
|
string |
The relative URI and unique identifier of the transaction resource this captures 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. |
└─➔ 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
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 [Credit card captures]
activate SwedbankPay
SwedbankPay-->>-Merchant: transaction resource
Et voilà! The payment should now be complete, secure and everyone should be happy. But, sometimes you also need to implement the cancellation and reversal operations described in After Payment.