Unscheduled Purchase
An unscheduled purchase
, also called a Merchant Initiated Transaction (MIT),
is a payment which uses a unscheduledToken
generated through a previous
payment in order to charge the same card at a later time. They are done by the
merchant without the cardholder being present.
Unscheduled purchase
s can be used in cases where you have an agreement with
your customer which handles both recurring orders and/or singular transactions.
Observe - it’s important that the Terms of Service clearly and understandably
states how the payment will be done towards your customer. Example use cases are
car rental companies charging the payer’s card for toll road expenses after the
rental period, or different subscription services and recurring orders where the
periodicity and/or amount varies.
Please note that you need to do a capture after sending the unscheduled request. We have added a capture section at the end of this page for that reason.
Generating The Token
First, you need an initial transaction where the unscheduledToken
is generated
and connected. You do that by adding the field generateUnscheduledToken
in the
PaymentOrder
request and set the value to true
. The payer must complete the
purchase to activate the token. You can also use Verify to activate
tokens.
(Read more about deleting the unscheduled token here.)
Initial Unscheduled Request
The initial request should look like this:
Request
1
2
3
4
POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.x/2.0 // Version optional for 3.0 and 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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
{
"paymentorder": {
"operation": "Purchase",
"currency": "SEK",
"amount": 1500,
"vatAmount": 375,
"description": "Test Purchase",
"userAgent": "Mozilla/5.0...",
"language": "sv-SE",
"generateUnscheduledToken": true,
"urls": {
"hostUrls": [ "https://example.com", "https://example.net" ],
"paymentUrl": "https://example.com/perform-payment", // Seamless View only
"completeUrl": "https://example.com/payment-completed",
"cancelUrl": "https://example.com/payment-cancelled",
"callbackUrl": "https://api.example.com/payment-callback",
"termsOfServiceUrl": "https://example.com/termsandconditions.pdf",
"logoUrl": "https://example.com/logo.png"
},
"payeeInfo": {
"payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
"payeeReference": "AB832",
"payeeName": "Merchant1",
"productCategory": "A123",
"orderReference": "or-123456",
"subsite": "MySubsite",
},
"payer": {
"digitalProducts": false,
"firstName": "Leia"
"lastName": "Ahlström"
"email": "leia@swedbankpay.com",
"msisdn": "+46787654321",
"payerReference": "AB1234",
"shippingAddress": {
"firstName": "firstname/companyname",
"lastName": "lastname",
"email": "karl.anderssson@mail.se",
"msisdn": "+46759123456",
"streetAddress": "string",
"coAddress": "string",
"city": "Solna",
"zipCode": "17674",
"countryCode": "SE"
},
"billingAddress": {
"firstName": "firstname/companyname",
"lastName": "lastname",
"email": "karl.anderssson@mail.se",
"msisdn": "+46759123456",
"streetAddress": "string",
"coAddress": "string",
"city": "Solna",
"zipCode": "17674",
"countryCode": "SE"
},
"accountInfo": {
"accountAgeIndicator": "04",
"accountChangeIndicator": "04",
"accountPwdChangeIndicator": "01",
"shippingAddressUsageIndicator": "01",
"shippingNameIndicator": "01",
"suspiciousAccountActivity": "01",
}
},
"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": 5,
"quantityUnit": "pcs",
"unitPrice": 300,
"discountPrice": 0,
"vatPercent": 2500,
"amount": 1500,
"vatAmount": 375
}
],
"riskIndicator": {
"deliveryEmailAddress": "olivia.nyhuus@swedbankpay.com",
"deliveryTimeFrameIndicator": "01",
"preOrderDate": "19801231",
"preOrderPurchaseIndicator": "01",
"shipIndicator": "01",
"giftCardPurchase": false,
"reOrderPurchaseIndicator": "01",
"pickUpAddress": {
"name": "Olivia Nyhus",
"streetAddress": "Saltnestoppen 43",
"coAddress": "",
"city": "Saltnes",
"zipCode": "1642",
"countryCode": "NO"
}
}
}
}
paymentOrder
object
check
operation
string
check
Determines the initial operation, defining the type of payment order created. Possible options are Purchase, Abort Verify, Unscheduled, Recur and Payout.
currency
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.
description
string
check
userAgent
string
check
The user agent of the payer. Should typically be set to the value of the User-Agent
header sent by the payer’s web browser.
language
string
check
urls
object
check
urls
object, containing the URLs relevant for the payment order.
hostUrls
array
check
paymentUrl
string
The paymentUrl
represents the URL that Swedbank Pay will redirect back to when the view-operation needs to be loaded, to inspect and act on the current status of the payment, such as when the payer is redirected out of the Seamless View (the <iframe>
) and sent back after completing the payment. paymentUrl
is only used in Seamless Views and should point to the page of where the Payment Order Seamless View is hosted. If both cancelUrl
and paymentUrl
is sent, the paymentUrl
will used.
completeUrl
string
check
The URL that Swedbank Pay will redirect back to when the payer has completed their interactions with the payment. This does not indicate a successful payment, only that it has reached a final (complete) state. A GET
request needs to be performed on the payment order to inspect it further. See completeUrl
for details.
cancelUrl
string
abort
request of the payment
or paymentorder
.
callbackUrl
string
check
The URL that Swedbank Pay will perform an HTTP POST
against every time a transaction is created on the payment order. See callback for details.
termsOfServiceUrl
string
check
The URL to the terms of service document which the payer must accept in order to complete the payment. HTTPS is a requirement.
logoUrl
string
check
With permission and activation on your contract (if you are using Seamless View), sending in a logoUrl
will replace the Swedbank Pay logo with the logo sent in. If you do not send in a logoUrl
, then no logo and no text is shown. Without permission or activation on your contract, sending in a logoUrl
has no effect. The logo must be a picture with maximum 50px height and 400px width. Requires HTTPS. Read more about this in Custom Logo .
payeeInfo
object
check
The payeeInfo
object, containing information about the payee (the recipient of the money). See payeeInfo
for details.
payeeId
string
check
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.
payeeName
string
productCategory
string(50)
orderReference
string(50)
subsite
string(40)
The subsite
field can be used to perform a split settlement on the payment. The different subsite
values must be resolved with Swedbank Pay reconciliation before being used. If you send in an unknown subsite
value, it will be ignored and the payment will be settled using the merchant’s default settlement account. Must be in the format of A-Za-z0-9
.
payer
object
payer
object containing information about the payer relevant for the payment order.
digitalProducts
bool
true
for merchants who only sell digital goods and only require email
and/or msisdn
as shipping details. Set to false
if the merchant also sells physical goods.
firstName
string
lastName
string
email
string
msisdn
string
shippingAddress
object
payer
. The field is related to 3-D Secure 2.
firstName
string
lastName
string
streetAddress
string
coAddress
string
zipCode
string
city
string
countryCode
string
billingAddress
object
check
firstName
string
lastName
string
streetAddress
string
check
coAddress
string
zipCode
string
check
city
string
check
countryCode
string
check
SE
, NO
, or FI
.
accountInfo
object
payer
containing info about the payer's account.
accountAgeIndicator
string
01
(No account, guest checkout) 02
(Created during this transaction) 03
(Less than 30 days old) 04
(30 to 60 days old) 05
(More than 60 days old)
accountChangeIndicator
string
01
(Changed during this transaction) 02
(Less than 30 days ago) 03
(30 to 60 days ago) 04
(More than 60 days ago)
accountChangePwdIndicator
string
01
(No changes) 02
(Changed during this transaction) 03
(Less than 30 days ago) 04
(30 to 60 days ago) 05
(More than 60 days old)
shippingAddressUsageIndicator
string
01
(This transaction) 02
(Less than 30 days ago) 03
(30 to 60 days ago) 04
(More than 60 days ago)
shippingNameIndicator
string
01
(Account name identical to shipping name) 02
(Account name different from shipping name)
suspiciousAccountActivity
string
01
(No suspicious activity has been observed) 02
(Suspicious activity has been observed)
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
string
check
PRODUCT
, SERVICE
, SHIPPING_FEE
, PAYMENT_FEE
DISCOUNT
, VALUE_CODE
or OTHER
. The type of the order item. PAYMENT_FEE
is the amount you are charged with when you are paying with invoice. The amount can be defined in the amount
field below.
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
A textual description of the purchase. Maximum length is 40 characters.
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
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.
riskIndicator
array
deliveryEmailAdress
string
deliveryTimeFrameIndicator
string
01
(Electronic Delivery) 02
(Same day shipping) 03
(Overnight shipping) 04
(Two-day or more shipping)
preOrderDate
string
YYYYMMDD
preOrderPurchaseIndicator
string
01
(Merchandise available) 02
(Future availability)
shipIndicator
string
01
(Ship to cardholder's billing address) 02
(Ship to another verified address on file with merchant)03
(Ship to address that is different than cardholder's billing address)04
(Ship to Store / Pick-up at local store. Store address shall be populated in shipping address fields)05
(Digital goods, includes online services, electronic giftcards and redemption codes) 06
(Travel and Event tickets, not shipped) 07
(Other, e.g. gaming, digital service)
giftCardPurchase
bool
true
if this is a purchase of a gift card.
reOrderPurchaseIndicator
string
01
(First time ordered) 02
(Reordered).
pickUpAddress
object
shipIndicator
set to 04
, then prefill this with the payers pickUpAddress
of the purchase to decrease the risk factor of the purchase.
name
string
shipIndicator
set to 04
, then prefill this with the payers name
of the purchase to decrease the risk factor of the purchase.
streetAddress
string
shipIndicator
set to 04
, then prefill this with the payers streetAddress
of the purchase to decrease the risk factor of the purchase. Maximum 50 characters long.
coAddress
string
shipIndicator
set to 04
, then prefill this with the payers coAddress
of the purchase to decrease the risk factor of the purchase.
city
string
shipIndicator
set to 04
, then prefill this with the payers city
of the purchase to decrease the risk factor of the purchase.
zipCode
string
shipIndicator
set to 04
, then prefill this with the payers zipCode
of the purchase to decrease the risk factor of the purchase.
countryCode
string
shipIndicator
set to 04
, then prefill this with the payers countryCode
of the purchase to decrease the risk factor of the purchase.Initial Unscheduled 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
38
39
40
41
42
{
"paymentorder": {
"id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"created": "2020-06-22T10:56:56.2927632Z",
"updated": "2020-06-22T10:56:56.4035291Z",
"operation": "Purchase",
"state": "Ready",
"currency": "SEK",
"amount": 1500,
"vatAmount": 375,
"description": "Test Purchase",
"initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
"language": "sv-SE",
"availableInstruments": [
"CreditCard",
"Trustly" ],
"integration": "HostedView", //For Seamless View integrations
"integration": "Redirect", //For Redirect integrations
"instrumentMode": false,
"guestMode": false,
"payer": {
"id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/payers"
},
"orderItems": {
"id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/orderitems"
}
},
"operations": [
{
"href": "https://api.payex.com/psp/paymentorders/222a50ca-b268-4b32-16fa-08d6d3b73224",
"rel":"update-order",
"method":"PATCH",
"contentType":"application/json"
},
{
"href": "https://api.payex.com/psp/paymentorders/222a50ca-b268-4b32-16fa-08d6d3b73224",
"rel": "abort",
"method": "PATCH",
"contentType": "application/json"
}
]
}
paymentOrder
object
id
string
The relative URL and unique identifier of the paymentorder
resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
created
string
updated
string
operation
string
Determines the initial operation, defining the type of payment order created. Possible options are Purchase, Abort Verify, Unscheduled, Recur and Payout.
state
string
Ready
, Pending
, Failed
or Aborted
. Indicates the state of the payment order. Does not reflect the state of any ongoing payments initiated from the payment order. This field is only for status display purposes.
currency
string
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(40)
A textual description of the purchase. Maximum length is 40 characters.
initiatingSystemUserAgent
string
The user agent of the HTTP client making the request, reflecting the value sent in the User-Agent
header with the initial POST
request which created the Payment Order.
language
string
sv-SE
, nb-NO
, da-DK
, en-US
or fi-FI
.
instrumentMode
bool
true
or false
. Indicates if the payment is initialized with only one payment method available.
guestMode
bool
true
or false
. Indicates if the payer chose to pay as a guest or not. When using the Payments Only implementation, this is triggered by not including a payerReference
in the original paymentOrder
request.
payer
id
payer
resource where information about the payer can be retrieved.
orderItems
id
orderItems
resource where information about the order items can be retrieved.
operations
array
The array of operations that are possible to perform on the payment order in its current state.
GET The Token
You can retrieve it by using the expand option when you GET
your payment. The
GET
request should look like the one below, with a ?$expand=paid
after the
paymentOrderId
. The response should match the initial payment response, but
with an expanded paid
field.
Request
1
2
3
4
GET /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/ HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.x/2.0 // Version optional for 3.0 and 2.0
Performing The Unscheduled Purchase
When you are ready to perform the unscheduled purchase, simply add the
unscheduledToken
field to the paymentOrder
request and use the token as the
value. Your request should look like the example below, and the response will
match the paymentOrder
response from the initial purchase.
After The Unscheduled Purchase
Please remember that the unscheduled
request will reserve the amount, but not
charge it. You will (i.e. when you are ready to ship purchased physical
products) have to perform a Capture request later
on to complete the unscheduled purchase. You can also
Cancel it if needed.
Unscheduled Request
Request
1
2
3
4
POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.x/2.0 // Version optional for 3.0 and 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
38
39
40
41
42
43
44
45
{
"paymentorder": {
"operation": "UnscheduledPurchase",
"unscheduledToken": "7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"currency": "NOK",
"amount": 1500,
"vatAmount": 0,
"description": "Test Unscheduled Purchase",
"userAgent": "Mozilla/5.0...",
"language": "nb-NO",
"urls": {
"callbackUrl": "https://example.com/payment-callback" // Callbacks will only be sent for Trustly
},
"payeeInfo": {
"payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b"
"payeeReference": "CD1234",
"payeeName": "Merchant1",
"productCategory": "A123",
"orderReference": "or-12456",
"subsite": "MySubsite",
},
"payer": {
"payerReference": "AB1234",
},
"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
}
]
}
}
paymentOrder
object
check
operation
object
check
UnscheduledPurchase
.
unscheduledToken
string
check
unscheduledToken
, if operation: Verify
, operation: UnscheduledPurchase
or generateUnscheduledToken: true
was used.
currency
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.
description
string
check
A textual description of the purchase. Maximum length is 40 characters.
userAgent
string
check
The user agent of the payer. Should typically be set to the value of the User-Agent
header sent by the payer’s web browser.
language
string
check
sv-SE
, nb-NO
, da-DK
, en-US
or fi-FI
.
implementation
string
urls
string
check
urls
resource where all URLs related to the payment order can be retrieved.
callbackUrl
string
check
The URL that Swedbank Pay will perform an HTTP POST
against every time a transaction is created on the payment order. See callback for details.
payeeInfo
object
check
The payeeInfo
object, containing information about the payee (the recipient of the money). See payeeInfo
for details.
payeeId
string
check
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
.
payeeName
string
check
productCategory
string(50)
check
orderReference
string(50)
check
subsite
string(40)
check
The subsite
field can be used to perform a split settlement on the payment. The different subsite
values must be resolved with Swedbank Pay reconciliation before being used. If you send in an unknown subsite
value, it will be ignored and the payment will be settled using the merchant’s default settlement account. Must be in the format of A-Za-z0-9
.
payer
string
payer
object, containing information about the payer.
payerReference
string
metadata
object
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
string
check
PRODUCT
, SERVICE
, SHIPPING_FEE
, PAYMENT_FEE
DISCOUNT
, VALUE_CODE
or OTHER
. The type of the order item. PAYMENT_FEE
is the amount you are charged with when you are paying with invoice. The amount can be defined in the amount
field below.
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
A textual description of the purchase. Maximum length is 40 characters.
discountDescription
string
quantity
integer
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
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.
restrictedToInstruments
array
Invoice
only. Invoice
supports the subtypes PayExFinancingNo
, PayExFinancingSe
and PayMonthlyInvoiceSe
, separated by a dash, e.g.; Invoice-PayExFinancingNo
. Default value is all supported payment methods. Use of this field requires an agreement with Swedbank Pay. You can restrict fees and/or discounts to certain payment methods by adding this field to the orderline you want to restrict. Use positive amounts to add fees and negative amounts to add discounts.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