Capture
Captures are only possible when a payment has a successful Authorization
transaction, naturally excluding one-phase payment methods like Swish and
Trustly. They will be marked as a Sale
transaction. Two-phase payment methods
like card and Vipps however, require a Capture
to be completed.
Please note that you have a maximum of 5 consecutive failed attempts at a capture. The payment will be locked after the fifth, and you need to contact us for further attempts.
In addition to full captures, it is possible to do partial captures of the authorized amount. You can do more captures on the same payment later, up to the total authorized amount. A useful tool for when you have to split orders into several shipments.
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.
To capture the authorized payment, we need to perform capture
against the
accompanying href
returned in the operations
list. See the abbreviated
request and response below:
Capture Request
Request
1
2
3
4
POST /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/captures HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.0/2.0 // Version optional
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
{
"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
}
]
}
}
transaction
object
check
description
string
check
amount
integer
check
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
check
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.
payeeReference
string(30)
check
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(30)
A unique reference to the transaction, provided by the merchant. Can be used as an invoice or receipt number as a supplement to payeeReference
.
orderItems
array
check
The array of items being purchased with the order. Note that authorization orderItems
will not be printed on invoices, so lines meant for print must be added in the Capture request. The authorization orderItems
will, however, be used in the Merchant Portal when captures or reversals are performed, and might be shown other places later. It is required to use this field to be able to send Capture orderItems
. Capture
requests should only contain items meant to be captured from the order.
reference
string
check
name
string
check
type
enum
check
PRODUCT
, SERVICE
, SHIPPING_FEE
, PAYMENT_FEE
, DISCOUNT
, VALUE_CODE
or OTHER
. The type of the order item.
class
string
check
MobilePhone
. Note that class
cannot contain spaces and must follow the regex pattern [\w-]*
. Swedbank Pay may use this field for statistics.
itemUrl
string
imageUrl
string
description
string
discountDescription
string
quantity
number
check
quantityUnit
string
check
pcs
, grams
, or similar. This is used for your own book keeping.
unitPrice
integer
check
discountPrice
integer
vatPercent
integer
check
25%
becomes 2500
.
amount
integer
check
10000
equals 100.00 SEK
and 5000
equals 50.00 SEK
.
vatAmount
integer
check
10000
equals 100.00 SEK
and 5000
equals 50.00 SEK
.
reference
string
check
name
string
check
type
enum
check
PRODUCT
, SERVICE
, SHIPPING_FEE
, PAYMENT_FEE
, DISCOUNT
, VALUE_CODE
or OTHER
. The type of the order item.
class
string
check
itemUrl
string
imageUrl
string
description
string
discountDescription
string
quantity
number
check
quantityUnit
string
check
pcs
, grams
, or similar.
unitPrice
integer
check
discountPrice
integer
vatPercent
integer
check
25%
becomes 2500
.
amount
integer
check
10000
equals 100.00 NOK
and 500
0 equals 50.00 NOK
.
vatAmount
integer
check
10000
equals 100.00 NOK
and 500
0 equals 50.00 NOK
.Capture Response
If the capture request succeeds, this should be the response:
Response
1
2
3
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.0/2.0
api-supported-versions: 3.0/2.0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"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": "2020-06-22T10:56:56.2927632Z",
"updated": "2020-06-22T10:56:56.4035291Z",
"type": "Capture",
"state": "Completed",
"amount": 1500,
"vatAmount": 375,
"description": "Capturing the authorized payment",
"payeeReference": "AB832",
"receiptReference": "AB831"
}
}
}
payment
string
capture
object
id
string
transaction
object
The object representation of the generic transaction
resource, containing information about the current transaction.
id
string
transaction
resource.
created
string
updated
string
type
string
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
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(30)
payeeReference
as an additional receipt number.Capture Sequence Diagram
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: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 methods that support <br>Authorizations.
end