Payment Orders
In order to initialize the Payment Menu, you need to create a Payment Order.
The paymentorders
resource and how you interact with it is described below.
The paymentorders
resource is used when initiating a payment process through
Payment Menu. The payment order is a container for the payment instrument
object selected by the payer. This will generate a payment that is accessed
through the sub-resources payments
and currentPayment
.
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
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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
HTTP/1.1 200 OK
Content-Type: application/json
{
"paymentorder": {
"id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"created": "2018-09-14T13:21:29.3182115Z",
"updated": "2018-09-14T13:21:57.6627579Z",
"operation": "Purchase",
"state": "Ready",
"currency": "SEK",
"amount": 1500,
"vatAmount": 0,
"remainingCaptureAmount": 1500,
"remainingCancellationAmount": 1500,
"remainingReversalAmount": 0,
"description": "Test Purchase",
"initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
"userAgent": "Mozilla/5.0...",
"language": "nb-NO",
"urls" : { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/urls" },
"payeeInfo" : { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payeeinfo" },
"settings": { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/settings" },
"payers": { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payers" },
"orderItems" : { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/orderItems" },
"metadata": { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/metadata" },
"payments": { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payments" },
"currentPayment": { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/currentpayment" }
},
"operations": [
{
"method": "PATCH",
"href": "https://api.externalintegration.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"rel": "update-paymentorder-abort",
"contentType": "application/json"
},
{
"method": "GET",
"href": "https://ecom.externalintegration.payex.com/paymentmenu/5a17c24e-d459-4567-bbad-aa0f17a76119",
"rel": "redirect-paymentorder",
"contentType": "text/html"
},
{
"method": "GET",
"href": "https://ecom.externalintegration.payex.com/paymentmenu/core/scripts/client/px.paymentmenu.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119&culture=nb-NO",
"rel": "view-paymentorder",
"contentType": "application/javascript"
}
]
}
Field | Type | Description |
---|---|---|
paymentorder |
object |
The payment order object. |
└➔ id
|
string |
The relative URI and unique identifier of the paymentorder resource . Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ created
|
string |
The ISO-8601 date of when the payment order was created. |
└➔ updated
|
string |
The ISO-8601 date of when the payment order was updated. |
└➔ operation
|
string |
Purchase |
└➔ 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 |
The currency of the payment order. |
└➔ 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 40 character length textual description of the purchase. |
└➔ userAgent
|
string |
The user agent string of the payer’s browser. |
└➔ language
|
string |
sv-SE , nb-NO or en-US . |
└➔ urls
|
string |
The URI to the urls resource where all URIs related to the payment order can be retrieved. |
└➔ payeeInfo
|
string |
The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details. |
└➔ payers
|
string |
The URI to the payers resource where information about the payee of the payment order can be retrieved. |
└➔ orderItems
|
string |
|
└➔ metadata
|
string |
The URI to the payments resource where information about all underlying payments can be retrieved. |
└➔ payments
|
string |
The URI to the payments resource where information about all underlying payments can be retrieved. |
└➔ currentPayment
|
string |
The URI to the currentPayment resource where information about the current – and sole active – payment can be retrieved. |
└➔ operations
|
array |
The array of possible operations to perform, given the state of the payment order. See Operations for details. |
Creating a payment order
To create a payment order, you perform a POST
request towards the
paymentorders
resource:
Request
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
POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"paymentorder": {
"operation": "Purchase",
"currency": "SEK",
"amount": 1500,
"vatAmount": 375,
"description": "Test Purchase",
"userAgent": "Mozilla/5.0...",
"language": "sv-SE",
"instrument": null,
"generateRecurrenceToken": true,
"generatePaymentToken": true,
"urls": {
"hostUrls": [ "https://example.com", "https://example.net" ],
"completeUrl": "https://example.com/payment-completed",
"cancelUrl": "https://example.com/payment-canceled",
"paymentUrl": "https://example.com/perform-payment",
"callbackUrl": "https://api.example.com/payment-callback",
"termsOfServiceUrl": "https://example.com/termsandconditoons.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": {
"email": "olivia.nyhuus@payex.com",
"msisdn": "+4798765432",
"workPhoneNumber" : "+4787654321",
"homePhoneNumber" : "+4776543210"
},
"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": "I1",
"name": "InvoiceFee",
"type": "PAYMENT_FEE",
"class": "Fees",
"description": "Fee for paying with Invoice",
"quantity": 1,
"quantityUnit": "pcs",
"unitPrice": 1900,
"vatPercent": 0,
"amount": 1900,
"vatAmount": 0,
"restrictedToInstruments": [
"Invoice-PayExFinancingSe"
]
}
],
"riskIndicator": {
"deliveryEmailAddress": "olivia.nyhuus@payex.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"
}
}
}
}
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
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
POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
"paymentorder": {
"id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"instrument": "CreditCard",
"paymentToken" : "5a17c24e-d459-4567-bbad-aa0f17a76119",
"created": "2020-06-22T10:56:56.2927632Z",
"updated": "2020-06-22T10:56:56.4035291Z",
"operation": "Purchase",
"state": "Ready",
"currency": "SEK",
"amount": 10000,
"vatAmount": 0,
"orderItems": {
"id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/orderitems"
},
"description": "test description",
"initiatingSystemUserAgent": "Mozilla/5.0",
"userAgent": "Mozilla/5.0",
"language": "sv-SE",
"urls": {
"id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/urls"
},
"payeeInfo": {
"id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payeeInfo"
},
"payments": {
"id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payments"
},
"currentPayment": {
"id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/currentpayment"
},
"items": [
{
"creditCard": {
"cardBrands": [
"Visa",
"MasterCard"
]
}
}
]
}
"operations": [
{
"method": "PATCH",
"href": "https://ecom.externalintegration.payex.com/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"rel": "update-paymentorder-updateorder",
"contentType": "application/json"
},
{
"method": "PATCH",
"href": "https://api.externalintegration.payex.com/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"rel": "update-paymentorder-abort",
"contentType": "application/json"
},
{
"method": "PATCH",
"href": "https://ecom.externalintegration.payex.com/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"rel": "update-paymentorder-expandinstrument",
"contentType": "application/json"
},
{
"method": "GET",
"href": "https://ecom.externalintegration.payex.com/paymentmenu/5a17c24e-d459-4567-bbad-aa0f17a76119",
"rel": "redirect-paymentorder",
"contentType": "text/html"
},
{
"method": "GET",
"href": "https://ecom.externalintegration.payex.com/paymentmenu/core/scripts/client/px.paymentmenu.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119&culture=nb-NO",
"rel": "view-paymentorder",
"contentType": "application/javascript"
}
]
}
Required | Field | Type | Description | |
---|---|---|---|---|
check | paymentorder |
object |
The payment order object. | |
check | └➔ operation
|
string |
The operation that the payment order is supposed to perform. | |
check | └➔ currency
|
string |
The currency of the payment. | |
check | └➔ 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. |
|
check | └➔ 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. |
|
check | └➔ description
|
string |
The description of the payment order. | |
check | └➔ instrument
|
string |
The payment instrument used. Selected by using the Instrument Mode. | |
check | └➔ generateRecurrenceToken
|
bool |
Determines whether a recurrence token should be generated. A recurrence token is primarily used to enable future recurring payments – with the same token – through server-to-server calls. Default value is false . |
|
check | └➔ generatePaymentToken
|
bool |
true or false . Set this to true if you want to create a paymentToken to use in future One Click Payments. |
|
check | └➔ userAgent
|
string |
The user agent of the payer. | |
check | └➔ language
|
string |
The language of the payer. | |
check | └➔ urls
|
object |
The urls object, containing the URLs relevant for the payment order. |
|
check | └─➔ hostUrls
|
array |
The array of URIs valid for embedding of Swedbank Pay Hosted Views. | |
check | └─➔ completeUrl
|
string |
The URL that Swedbank Pay will redirect back to when the payer has completed his or her 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 |
The URI to redirect the payer to if the payment is canceled, either by the payer or by the merchant trough an abort request of the payment or paymentorder . |
||
└─➔ paymentUrl
|
string |
The URI that Swedbank Pay will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. See paymentUrl for details. |
||
check | └─➔ callbackUrl
|
string |
The URI to the API endpoint receiving POST requests on transaction activity related to the payment order. |
|
check | └─➔ termsOfServiceUrl
|
string |
The URI to the terms of service document the payer must accept in order to complete the payment. Note that this field is not required unless generateReferenceToken or generateRecurrenceToken is also submitted in the request. This is the Merchants, not the Swedbank Pay Terms of Service. HTTPS is a requirement. |
|
check | └─➔ logoUrl
|
string |
With permission and activation on your contract, 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. Read more about this in Custom Logo. |
|
check | └➔ payeeInfo
|
string |
The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details. |
|
check | └─➔ payeeId
|
string |
The ID of the payee, usually the merchant ID. | |
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. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined. |
|
└─➔ payeeName
|
string |
The name of the payee, usually the name of the merchant. | ||
└─➔ productCategory
|
string |
A product category or number sent in from the payee/merchant. This is not validated by Swedbank Pay, but will be passed through the payment process and may be used in the settlement process. | ||
└─➔ orderReference
|
string(50) |
The order reference should reflect the order reference found in the merchant’s systems. | ||
└─➔ subsite
|
String(40) |
The subsite field can be used to perform split settlement on the payment. The subsites must be resolved with Swedbank Pay reconciliation before being used. | ||
└➔ payer
|
object |
The payer object containing information about the payer relevant for the payment order. |
||
└─➔ email
|
string |
The e-mail address of the payer. Will be used to prefill the Checkin as well as on the payer’s profile, if not already set. Increases the chance for frictionless 3-D Secure 2 flow. | ||
└─➔ msisdn
|
string |
The mobile phone number of the Payer. Will be prefilled on Checkin page and used on the payer’s profile, if not already set. The mobile number must have a country code prefix and be 8 to 15 digits in length. The field is related to 3-D Secure 2. | ||
└─➔ workPhoneNumber
|
string |
The work phone number of the payer. Optional (increased chance for frictionless flow if set) and is related to 3-D Secure 2. | ||
└─➔ homePhoneNumber
|
string |
The home phone number of the payer. Optional (increased chance for frictionless flow if set) and is related to 3-D Secure 2. | ||
check | └➔ orderItems
|
array |
The array of items being purchased with the order. Used to print on invoices if the payer chooses to pay with invoice, among other things. orderItems is required in all requests. In capture requests it should only contain the items to be captured from the order. |
|
check | └─➔ reference
|
string |
A reference that identifies the order item. | |
check | └─➔ name
|
string |
The name of the order item. | |
check | └─➔ type
|
string |
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. |
|
check | └─➔ class
|
string |
The classification of the order item. Can be used for assigning the order item to a specific product category, such as MobilePhone . Note that class cannot contain spaces and must follow the regex pattern [\w-]* . Swedbank Pay may use this field for statistics. |
|
└─➔ itemUrl
|
string |
The URL to a page that can display the purchased item, product or similar. | ||
︎︎︎ | └─➔ imageUrl
|
string |
The URL to an image of the order item. | |
└─➔ description
|
string |
A 40 character length textual description of the purchase. | ||
└─➔ discountDescription
|
string |
The human readable description of the possible discount. | ||
check | └─➔ quantity
|
integer |
The 4 decimal precision quantity of order items being purchased. | |
check | └─➔ quantityUnit
|
string |
The unit of the quantity, such as pcs , grams , or similar. This is used for your own book keeping. |
|
check | └─➔ unitPrice
|
integer |
The price per unit of order item, including VAT. | |
└─➔ discountPrice
|
integer |
If the order item is purchased at a discounted price. This field should contain that price, including VAT. | ||
check | └─➔ vatPercent
|
integer |
The percent value of the VAT multiplied by 100, so 25% becomes 2500 . |
|
check | └─➔ 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. |
|
check | └─➔ 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. |
|
└➔ restrictedToInstruments
|
array |
CreditCard , Invoice , Vipps , Swish , Trustly and/or CreditAccount . Invoice supports the subtypes PayExFinancingNo , PayExFinancingSe and PayMonthlyInvoiceSe , separated by a dash, e.g.; Invoice-PayExFinancingNo . Limits the options available to the consumer in the payment menu. Default value is all supported payment instruments. Usage of this field requires an agreement with Swedbank Pay. |
||
└➔ riskIndicator
|
array |
This optional object consist of information that helps verifying the payer. Providing these fields decreases the likelihood of having to prompt for 3-D Secure authentication of the payer when they are authenticating the purchase. | ||
└─➔ deliveryEmailAdress
|
string |
For electronic delivery, the email address to which the merchandise was delivered. Providing this field when appropriate decreases the likelyhood of a 3-D Secure authentication for the payer. | ||
└─➔ deliveryTimeFrameIndicator
|
string |
Indicates the merchandise delivery timeframe. 01 (Electronic Delivery) 02 (Same day shipping) 03 (Overnight shipping) 04 (Two-day or more shipping) |
||
└─➔ preOrderDate
|
string |
For a pre-ordered purchase. The expected date that the merchandise will be available. Format: YYYYMMDD
|
||
└─➔ preOrderPurchaseIndicator
|
string |
Indicates whether the payer is placing an order for merchandise with a future availability or release date. 01 (Merchandise available) 02 (Future availability) |
||
└─➔ shipIndicator
|
string |
Indicates shipping method chosen for the transaction. 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 |
Indicates whether the cardholder is reordering previously purchased merchandise. 01 (First time ordered) 02 (Reordered). |
||
└➔ pickUpAddress
|
object |
If shipIndicator set to 04 , then prefill this with the payers pickUpAddress of the purchase to decrease the risk factor of the purchase. |
||
└─➔ name
|
string |
If shipIndicator set to 04 , then prefill this with the payers name of the purchase to decrease the risk factor of the purchase. |
||
└─➔ streetAddress
|
string |
If 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 |
If shipIndicator set to 04 , then prefill this with the payers coAddress of the purchase to decrease the risk factor of the purchase. |
||
└─➔ city
|
string |
If shipIndicator set to 04 , then prefill this with the payers city of the purchase to decrease the risk factor of the purchase. |
||
└─➔ zipCode
|
string |
If shipIndicator set to 04 , then prefill this with the payers zipCode of the purchase to decrease the risk factor of the purchase. |
||
└─➔ countryCode
|
string |
If shipIndicator set to 04 , then prefill this with the payers countryCode of the purchase to decrease the risk factor of the purchase. |
Field | Type | Description | |
---|---|---|---|
paymentorder |
object |
The payment order object. | |
└➔ id
|
string |
The relative URI and unique identifier of the paymentorder resource . Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
└➔ instrument
|
string |
The payment instrument used. Selected by using the Instrument Mode. | |
└➔ paymentToken
|
string |
The payment token created for the purchase used in the authorization to create One Click Payments. | |
└➔ created
|
string |
The ISO-8601 date of when the payment order was created. | |
└➔ updated
|
string |
The ISO-8601 date of when the payment order was updated. | |
└➔ operation
|
string |
Purchase |
|
└➔ 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 |
The currency of the payment order. | |
└➔ 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 40 character length textual description of the purchase. | |
└➔ userAgent
|
string |
The user agent string of the payer’s browser. | |
└➔ language
|
string |
sv-SE , nb-NO or en-US . |
|
└➔ urls
|
string |
The URI to the urls resource where all URIs related to the payment order can be retrieved. |
|
└➔ payeeInfo
|
string |
The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details. |
|
└➔ payers
|
string |
The URI to the payers resource where information about the payee of the payment order can be retrieved. |
|
└➔ orderItems
|
string |
The URI to the orderItems resource where information about the order items can be retrieved. |
|
└➔ metadata
|
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. |
|
└➔ payments
|
string |
The URI to the payments resource where information about all underlying payments can be retrieved. |
|
└➔ currentPayment
|
string |
The URI to the currentPayment resource where information about the current – and sole active – payment can be retrieved. |
|
└➔ operations
|
array |
The array of possible operations to perform, given the state of the payment order. See Operations for details. |
Description
The description
field is a 40 character length textual summary of the
purchase. It is needed to specify what payer is actually purchasing. Below you
will find an abbreviated Card Payments Purchase
request.
As you can see the description
field is set to be Test Description
in the the code example.
Notice that for Redirect,
the description will be shown as Test - Reference1583419461
, as set
in the code example. For the Seamless View scenario, the description is not
shown in the payment window, but it is still required in the initial request.
Request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
POST /psp/paymentorders/payments HTTP/1.1
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"paymentorder": {
"operation": "Purchase",
"intent": "Authorization",
"currency": "SEK",
"description": "Test Description",
"generateRecurrenceToken": false,
"userAgent": "Mozilla/5.0...",
"language": "sv-SE",
"urls":
"hostUrls": ["https://example.com"]
}
}
URLs
When creating a Payment Order, the urls
field of the paymentOrder
contains the related URIs, including where the payer is redirected when
going forward with or cancelling a payment session, as well as the callback URI
that is used to inform the payee (merchant) of changes or updates made to
underlying payments or transaction.
Required | Field | Type | Description |
---|---|---|---|
check ︎︎︎︎︎ | hostUrls |
array |
The array of URIs valid for embedding of Swedbank Pay Hosted Views. |
check | completeUrl |
string |
The URL that Swedbank Pay will redirect back to when the payer has completed his or her 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. |
check | termsOfServiceUrl |
string |
The URI to the terms of service document the payer must accept in order to complete the payment. Note that this field is not required unless generateReferenceToken or generateRecurrenceToken is also submitted in the request. This is the Merchants, not the Swedbank Pay Terms of Service. HTTPS is a requirement. |
cancelUrl |
string |
The URI to redirect the payer to if the payment is canceled, either by the payer or by the merchant trough an abort request of the payment or paymentorder . |
|
paymentUrl |
string |
The URI that Swedbank Pay will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. See paymentUrl for details. |
|
callbackUrl |
string |
The URI to the API endpoint receiving POST requests on transaction activity related to the payment order. |
|
logoUrl |
string |
With permission and activation on your contract, 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. Read more about this in Custom Logo. |
Payment Url
For our Seamless Views, the field called paymentUrl
will be used when the
payer is redirected out of the Seamless View (the iframe
). The payer is
redirected out of frame when selecting the payment
instrument Vipps or in the 3-D Secure verification for Credit Card Payments.
The URL should represent the page of where the Payment Order Seamless View was
hosted originally, such as the checkout page, shopping cart page, or similar.
Basically, paymentUrl
should be set to the same URL as that of the page where
the JavaScript for the Seamless View was added to in order to initiate the
payment process.
Please note that the paymentUrl
must be able to invoke the same JavaScript URL
from the same Payment Order as the one that initiated the payment process
originally, so it should include some sort of state identifier in the URL. The
state identifier is the ID of the order, shopping cart or similar that has the
URL of the Payment stored.
With paymentUrl
in place, the retry process becomes much more convenient for
both the integration and the payer.
paymentUrl
is used by the Seamless View flow and must be used for
WebView-based app implementations. Some payment instruments only work when
owning the full browser page (no use of <iframe>
), this will be solved by
doing a full browser (top frame) redirect out of the Seamless View. 3-D Secure
requires this, for example.
For mobile flows, some payment instruments work best when app-to-app switching is enabled and handled automatically (Swish, Vipps etc). To solve this, it is important that the third party app or site understand where to redirect the payer back to after the flow on their end is completed.
The paymentUrl
is the URL Swedbank Pay will provide to the third party for
handling the redirect back to your site or app. When receiving the payer back
on the paymentUrl
either in an app or web page, it is important to restore the
Seamless View to let the payment finalize the flow. For in-app it is important
that you either implement the onPaymentCompleted
event or let the Seamless
View redirect to the completeUrl
before intercepting the WebView. If you
intercept the WebView when the payer’s device is redirected to the paymentUrl
it can lead to issues. If you want to handle payment errors in your own code,
you should also subscribe to other events provided by the Seamless View
JavaScript and shut down the Seamless View if any of these events occur.
Events to subscribe to for full control over the payment flow are can be found in Payment Menu Events.
When implementing the Seamless View flow into a WebView in your mobile app, you
should use a custom scheme or Universal Link
in the paymentUrl
for handling automatic switching between your app and the
payment app on the mobile device.
URLs Resource
It is possible to perform a GET
request on the urls
resource to retrieve its
contents.
Request
1
2
3
4
GET /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/urls/ HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
HTTP/1.1 200 OK
Content-Type: application/json
{
"paymentorder": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"urls": {
"id": "/psp/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/urls",
"hostUrls": [ "https://example.com", "https://example.net" ],
"completeUrl": "https://example.com/payment-complete",
"cancelUrl": "https://example.com/payment-canceled",
"paymentUrl": "https://example.com/perform-payment",
"callbackUrl": "http://api.example.com/payment-callback",
"logoUrl": "http://merchant.com/path/to/logo.png",
"termsOfServiceUrl": "http://merchant.com/path/to/tems"
}
}
Field | Type | Description |
---|---|---|
paymentorder |
string |
The relative URI and unique identifier of the payment resource this urls belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
urls |
object |
The URLs object. |
└➔ id
|
string |
The relative URI and unique identifier of the urls resource this urls belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ hostsUrl
|
string |
An array of the whitelisted URIs that are allowed as parents to a Hosted View, typically the URI of the web shop or similar that will embed a Hosted View within it. |
└➔ completeUrl
|
string |
The URL that Swedbank Pay will redirect back to when the payer has completed his or her 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 |
The URI to redirect the payer to if the payment is canceled, either by the payer or by the merchant trough an abort request of the payment or paymentorder . |
└➔ paymentUrl
|
string |
The URI that Swedbank Pay will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. See paymentUrl for details. |
└➔ callbackUrl
|
string |
The URI that Swedbank Pay will perform an HTTP POST against every time a transaction is created on the payment. See callback) for details. |
└➔ logoUrl
|
string |
With permission and activation on your contract, 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. Read more about this in Custom Logo. |
└➔ termsOfServiceUrl
|
string |
The URI to the terms of service document the payer must accept in order to complete the payment. Note that this field is not required unless generateReferenceToken or generateRecurrenceToken is also submitted in the request. This is the Merchants, not the Swedbank Pay Terms of Service. HTTPS is a requirement. |
Order Items
The orderItems
field of the paymentOrder
is an array containing the items being purchased with the order. Used to print on invoices if the payer chooses to pay with invoice, among other things. orderItems
is required in all requests. It should be specified on both payment order creation as well as on Capture.
Required | Field | Type | Description |
---|---|---|---|
check | reference |
string |
A reference that identifies the order item. |
check | name |
string |
The name of the order item. |
check | type |
enum |
PRODUCT , SERVICE , SHIPPING_FEE , DISCOUNT , VALUE_CODE , or OTHER . The type of the order item. |
check | class |
string |
The classification of the order item. Can be used for assigning the order item to a specific product category, such as MobilePhone . Note that class cannot contain spaces and must follow the regex pattern [\w-]* . Swedbank Pay may use this field for statistics. |
itemUrl |
string |
The URL to a page that can display the purchased item, such as a product page | |
imageUrl |
string |
The URL to an image of the order item. | |
description |
string |
The human readable description of the order item. | |
discountDescription |
string |
The human readable description of the possible discount. | |
check | quantity |
decimal |
The 4 decimal precision quantity of order items being purchased. |
check | quantityUnit |
string |
The unit of the quantity, such as pcs , grams , or similar. |
check | unitPrice |
integer |
The price per unit of order item, including VAT. |
discountPrice |
integer |
If the order item is purchased at a discounted price. This field should contain that price, including VAT. | |
check | vatPercent |
integer |
The percent value of the VAT multiplied by 100, so 25% becomes 2500 . |
check | 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. |
check | 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. |
Items
The items
field of the paymentOrder
is an array containing items that will affect how the payment is performed.
Required | Field | Type | Description |
---|---|---|---|
creditCard |
object |
The credit card object. | |
└➔ rejectDebitCards
|
bool |
true if debit cards should be declined; otherwise false per default. Default value is set by Swedbank Pay and can be changed at your request. |
|
└➔ rejectDebitCards
|
bool |
true if debit cards should be declined; otherwise false per default. Default value is set by Swedbank Pay and can be changed at your request. |
|
└➔ rejectCreditCards
|
bool |
true if credit cards should be declined; otherwise false per default. Default value is set by Swedbank Pay and can be changed at your request. |
|
└➔ rejectConsumerCards
|
bool |
true if consumer cards should be declined; otherwise false per default. Default value is set by Swedbank Pay and can be changed at your request. |
|
└➔ rejectCorporateCards
|
bool |
true if corporate cards should be declined; otherwise false per default. Default value is set by Swedbank Pay and can be changed at your request. |
|
invoice |
object |
The invoice object. | |
└➔ feeAmount
|
integer |
The fee amount in the lowest monetary unit to apply if the payer chooses to pay with invoice. | |
swish |
object |
The swish object. | |
└➔ enableEcomOnly
|
bool |
true to only enable Swish on ecommerce transactions. |
The paymentOrders
resource utilize several sub-resources, relating to
underlying payments,
the current payment active,
payers and urls.
Common sub-resources like payeeinfo, that are
structurally identical for both payments and payments orders, are described in
the Payment Resources section.
Instrument Mode
In “Instrument Mode” the Payment Menu will display only one specific payment instrument instead of all configured on your merchant account. The Payment Order resource works just like it otherwise would, allowing you to remain largely indifferent to the payment instrument in use.
If you do not want to use Swedbank Pay Payment Menu or do have multiple payment
providers on your site we strongly recommend that you implement the “Instrument
Mode” functionality. To use this feature you will need to add the instrument
field to the request. This will make the Swedbank Pay Payment Menu only render
a single payment instrument. So even if Swedbank Pay is set up to provide more
than one instrument you will be able to let it only show one at a time.
It is important to use this feature if you want to build your own payment menu.
In this case you should use the instrument
field to enforce which payment
instrument to show. If you have an agreement with Swedbank Pay for both Card and
Swish/Vipps processing, and the payer chooses either of these instruments, you
should add the instrument
parameter with the specific payment instrument. If
the payer later changes their mind and chooses the other instrument, you can
make a call to Swedbank Pay to change the instrument on the active payment. This
is important because we do not allow creating multiple payments with the same
orderReference
. To ensure that you can still use the same orderReference
,
you should only make one payment for each purchase and change the instrument
to reflect what the payer has chosen in your menu.
The Payment Menu is switched to “Instrument Mode” by providing the request field
instrument
as described in the abbreviated example below.
Request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"paymentorder": {
"operation": "Purchase",
"currency": "SEK",
"amount": 1500,
"vatAmount": 375,
"description": "Test Purchase",
"userAgent": "Mozilla/5.0...",
"language": "sv-SE",
"instrument": "CreditCard"
"generateRecurrenceToken": true,
"generatePaymentToken": true,
"urls": {
"hostUrls": [ "https://example.com", "https://example.net" ],
}
}
}
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"paymentorder": {
"id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"instrument": "CreditCard"
"paymentToken" : "5a17c24e-d459-4567-bbad-aa0f17a76119",
"created": "2020-06-22T10:56:56.2927632Z",
"updated": "2020-06-22T10:56:56.4035291Z",
"operation": "Purchase",
"state": "Ready",
"currency": "SEK",
"amount": 1500,
"vatAmount": 375,
"orderItems": {
"id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/orderitems"
}
}
}
It is possible to switch instrument after the paymentOrder
has been created.
You can do this with the following PATCH
request, using Swish as an example.
1
2
3
4
5
6
7
8
9
10
11
PATCH /psp/paymentorders/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1 HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"paymentorder": {
"operation": "SetInstrument",
"instrument": "Swish"
}
}
The valid instruments for the paymentOrder
can be retrieved from the
availableInstruments
parameter in the paymentOrder
response. Using a
merchant set up with contracts for Creditcard
, Swish
and Invoice
,
availableInstruments
will look like this:
1
2
3
4
5
"availableInstruments": [
"CreditCard",
"Invoice-PayExFinancingSe",
"Swish"
],
Payer Aware Payment Menu
Please note that not all payment instruments provided by Swedbank Pay support Payer Awareness today.
To maximize the experience of your payers, you should implement the Payer Aware Payment Menu by identifying each payer with a unique identifier. It is important that you enforce a good SCA (Strong Consumer Authentication) strategy when authenticating the payer. The payer identifier must then be sent with the creation of the payment order to Swedbank Pay. This will enable Swedbank Pay to render a unique payment menu experience for each payer. It will also increase the chance for a frictionless payment.
By identifying your payers, they are able to store payment information for
future payments by setting the generatePaymentToken
value to true
. This will
enable the Swedbank Pay Payment Menu to show stored payment instrument details
for future purchases. The payer is, by default, asked if they want to store
their payment details, so even with generatePaymentToken
set to true
, it is
still up to the payer if they want the details stored or not.
GDPR Responsibility
Remember that the responsibility to enforce the GDPR requirements lies on you as a merchant.
As a part of these requirements, you have to facilitate that the payer can
remove active payment tokens when they want. It is up to you how to implement
this functionality on your side, but Swedbank Pay has the API you need to ensure
that cleaning up old data is easy. It is possible to query for all active
payment tokens registered on a specific payerReference
. This query will also
list the operations used for deleting tokens. You can choose to remove all
tokens for that payer or only a subset of all tokens connected to that
payerReference
.
BYO Payment Menu
Payment Menu is versatile and can be configured in such a way that it functions like a single payment instrument. In such configuration, it is easy to Bring Your Own Payment Menu, i.e. building a customized payment menu in our own user interface. For in-app integrations, the payers’ shopping experience will be better if you choose the BYO Payment Menu option. For web integrations, we highly recommend the Swedbank Pay Payment Menu.
The payerReference
can be used to list all active tokens here as well. This
will also list the payment instruments enumerated in the availableInstruments
,
as instrument-mode is mandatory when you are using BYO Payment Menu.
The alternative to the payerReference
option is to store paymentToken
s found
in the paymentOrder
s after the payment is completed. This requires that the
merchant makes sure the list of paymentToken
s is up to date at their end.
Add Stored Payment Instrument Details
When building a custom payment menu, features like adding new stored payment instrument details (i.e. “Add new card”) is something that needs to be provided in your UI.
This can be achieved by forcing the creation of a paymentToken
by setting
disableStoredPaymentDetails
to true
in a Purchase payment (if you want
to withdraw money and create the token in the same operation), or by performing
a Verify payment (without withdrawing any money).
Setting disableStoredPaymentDetails
to true
will turn off all stored payment
details for the current purchase. The payer will also not be asked if they
want to store the payment detail that will be part of the purchase. When you use
this feature it is important that you have asked the payer in advance if it
is ok to store their payment details for later use.
Most often you will use the disableStoredPaymentDetails
feature in combination
with the Instrument Mode capability. If you build your own
menu and want to show stored payment details, you will need to set the
disableStoredPaymentDetails
to true
. It is important that you then store the
paymentToken
in your system or call Swedbank Pay with the payerReference
to
get all active payment tokens registered on that payer when building your
menu. See the abbreviated Purchase
example below.
Request
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
POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"paymentorder": {
"operation": "Purchase",
"currency": "SEK",
"amount": 1500,
"vatAmount": 375,
"description": "Test Purchase",
"userAgent": "Mozilla/5.0...",
"language": "sv-SE",
"instrument": "CreditCard"
"generateRecurrenceToken": true,
"generatePaymentToken": true,
"disableStoredPaymentDetails": true,
"urls": {
"hostUrls": [ "https://example.com", "https://example.net" ],
"completeUrl": "https://example.com/payment-completed",
"cancelUrl": "https://example.com/payment-canceled",
"paymentUrl": "https://example.com/perform-payment",
"callbackUrl": "https://api.example.com/payment-callback",
"termsOfServiceUrl": "https://example.com/termsandconditoons.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": {
"payerReference": "AB1234",
}
}
}
Required | Field | Type | Description | |
---|---|---|---|---|
check | paymentorder |
object |
The payment order object. | |
check | └➔ operation
|
string |
The operation that the payment order is supposed to perform. | |
check | └➔ currency
|
string |
The currency of the payment. | |
check | └➔ 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. |
|
check | └➔ 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. |
|
check | └➔ description
|
string |
The description of the payment order. | |
check | └➔ instrument
|
string |
The payment instrument used. Selected by using the Instrument Mode. | |
check | └➔ generateRecurrenceToken
|
bool |
Determines whether a recurrence token should be generated. A recurrence token is primarily used to enable future recurring payments – with the same token – through server-to-server calls. Default value is false . |
|
check | └➔ generatePaymentToken
|
bool |
true or false . Set this to true if you want to create a paymentToken to use in future One Click Payments. |
|
└➔ disableStoredPaymentDetails
|
bool |
Setting to true will turn off all stored payment details for the current purchase. When you use this feature it is important that you have asked the payer in advance if it is ok to store their payment details for later use. |
||
check | └➔ userAgent
|
string |
The user agent of the payer. | |
check | └➔ language
|
string |
The language of the payer. | |
check | └➔ urls
|
object |
The urls object, containing the URLs relevant for the payment order. |
|
check | └─➔ hostUrls
|
array |
The array of URIs valid for embedding of Swedbank Pay Hosted Views. | |
check | └─➔ completeUrl
|
string |
The URL that Swedbank Pay will redirect back to when the payer has completed his or her 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 |
The URI to redirect the payer to if the payment is canceled, either by the payer or by the merchant trough an abort request of the payment or paymentorder . |
||
└─➔ paymentUrl
|
string |
The URI that Swedbank Pay will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. See paymentUrl for details. |
||
check | └─➔ callbackUrl
|
string |
The URI to the API endpoint receiving POST requests on transaction activity related to the payment order. |
|
check | └─➔ termsOfServiceUrl
|
string |
The URI to the terms of service document the payer must accept in order to complete the payment. Note that this field is not required unless generateReferenceToken or generateRecurrenceToken is also submitted in the request. This is the Merchants, not the Swedbank Pay Terms of Service. HTTPS is a requirement. |
|
check | └─➔ logoUrl
|
string |
With permission and activation on your contract, 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. Read more about this in Custom Logo. |
|
check | └➔ payeeInfo
|
string |
The payeeInfo object, containing information about the payee. |
|
check | └─➔ payeeId
|
string |
The ID of the payee, usually the merchant ID. | |
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. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined. |
|
└─➔ payeeName
|
string |
The name of the payee, usually the name of the merchant. | ||
└─➔ productCategory
|
string |
A product category or number sent in from the payee/merchant. This is not validated by Swedbank Pay, but will be passed through the payment process and may be used in the settlement process. | ||
└─➔ orderReference
|
string(50) |
The order reference should reflect the order reference found in the merchant’s systems. | ||
└─➔ subsite
|
String(40) |
The subsite field can be used to perform split settlement on the payment. The subsites must be resolved with Swedbank Pay reconciliation before being used. | ||
└➔ payer
|
string |
The payer object, containing information about the payer. |
||
└─➔ payerReference
|
string |
The reference to the payer from the merchant system, like e-mail address, mobile number, customer number etc. Also used in Payer Aware Payment Menu. Mandatory if generateReccurenceToken , RecurrenceToken , generatePaymentToken or paymentToken is true . |
Operations
When a payment order resource is created and during its lifetime, it will have a set of operations that can be performed on it. The state of the payment order resource, what the access token is authorized to do, the chosen payment instrument and its transactional states, etc. determine the available operations before the initial purchase. A list of possible operations and their explanation is given below.
Deprecated Operations.
Payment instrument-specific operations are passed
through Payment Order. These can be recognized by not having
paymentorder
in the rel
value. They will be described and marked as
deprecated in the operation list below.
Operations
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
{
"paymentorder": {
"id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
},
"operations": [
{
"method": "PATCH",
"href": "https://api.externalintegration.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"rel": "update-paymentorder-abort",
"contentType": "application/json"
},
{
"method": "PATCH",
"href": "https://api.externalintegration.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"rel": "update-paymentorder-updateorder",
"contentType": "application/json"
},
{
"method": "GET",
"href": "https://ecom.externalintegration.payex.com/paymentmenu/5a17c24e-d459-4567-bbad-aa0f17a76119",
"rel": "redirect-paymentorder",
"contentType": "text/html"
},
{
"method": "GET",
"href": "https://ecom.externalintegration.payex.com/paymentmenu/core/scripts/client/px.paymentmenu.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119&culture=nb-NO",
"rel": "view-paymentorder",
"contentType": "application/javascript"
},
{
"method": "POST",
"href": "https://api.externalintegration.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/captures",
"rel": "create-paymentorder-capture",
"contentType": "application/json"
},
{
"method": "POST",
"href": "https://api.externalintegration.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/cancellations",
"rel": "create-paymentorder-cancel",
"contentType": "application/json"
},
{
"method": "POST",
"href": "https://api.externalintegration.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/reversals",
"rel": "create-paymentorder-reversal",
"contentType": "application/json"
},
{
"method": "GET",
"href": "https://api.externalintegration.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/paid",
"rel": "paid-paymentorder",
"contentType": "application/json"
},
{
"method": "GET",
"href": "https://api.externalintegration.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/failed",
"rel": "failed-paymentorder",
"contentType": "application/problem+json"
},
{
// Deprecated operation. Do not use!
"method": "POST",
"href": "https://api.externalintegration.payex.com/psp/creditcard/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures",
"rel": "create-capture",
"contentType": "application/json"
},
{
// Deprecated operation. Do not use!
"method": "POST",
"href": "https://api.externalintegration.payex.com/psp/creditcard/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations",
"rel": "create-cancel",
"contentType": "application/json"
},
{
// Deprecated operation. Do not use!
"method": "POST",
"href": "https://api.externalintegration.payex.com/psp/creditcard/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals",
"rel": "create-reversal",
"contentType": "application/json"
}
]
}
Field | Type | Description |
---|---|---|
href |
string |
The target URI to perform the operation against. |
rel |
string |
The name of the relation the operation has to the current resource. |
method |
string |
GET , PATCH , POST , etc. The HTTP method to use when performing the operation. |
contentType |
string |
The HTTP content type of the resource referenced in the href field. |
The operations should be performed as described in each response and not as
described here in the documentation. Always use the href
and method
as
specified in the response by finding the appropriate operation based on its
rel
value. The only thing that should be hard coded in the client is the value
of the rel
and the request that will be sent in the HTTP body of the request
for the given operation.
Operation | Description |
---|---|
update-paymentorder-abort |
Aborts the payment order before any financial transactions are performed. |
update-paymentorder-updateorder |
Updates the order with a change in the amount and/or vatAmount . |
redirect-paymentorder |
Contains the URI that is used to redirect the payer to the Swedbank Pay Payments containing the Payment Menu. |
view-paymentorder |
Contains the JavaScript href that is used to embed the Payment Menu UI directly on the webshop/merchant site. |
create-paymentorder-capture |
The second part of a two-phase transaction where the authorized amount is sent from the payer to the payee. It is possible to do a part-capture on a subset of the authorized amount. Several captures on the same payment are possible, up to the total authorization amount. |
create-paymentorder-cancel |
Used to cancel authorized and not yet captured transactions. If a cancellation is performed after doing a part-capture, it will only affect the not yet captured authorization amount. |
create-paymentorder-reversal |
Used to reverse a payment. It is only possible to reverse a payment that has been captured and not yet reversed. |
paid-paymentorder |
Returns the information about a paymentorder that has the status paid . |
failed-paymentorder |
Returns the information about a paymentorder that has the status failed . |
create-capture |
Deprecated operation. Do not use! |
create-cancel |
Deprecated operation. Do not use! |
create-cancel |
Deprecated operation. Do not use! |
Payment Order State
The state
field on the authorization
does not indicate whether a given
transaction
was successful or not, it only tells whether the authorization
resource itself is operational or not. To figure out the state
of i.e. authorization transactions
, you have two options:
Paid or Failed Operations
You can perform a GET
request on the authorization. As long as the
authorization has been completed, successful or not, you will find the
Paid
or Failed
operation among the operations in the response.
Please note that a authorization where a Failed
attempt has been made,
but the payer still has attempts left to complete the authorization, you
won’t see the Failed
operation. It will only appear when all attempts have
been made.
Authorization or Sale Transactions
Find the authorization’s list of transactions
either by expanding it when
retrieving the authorization, or by performing a GET
request towards the
transactions.id
URI.
If you find a transaction
with type
equal to authorization, with its
state
equal to Completed
, you can be sure that the amount of the
authorization has been reserved or withdrawn and that the authorization
can be considered successful.
CompleteUrl
This URL will be used by Swedbank Pay when a payment is Completed
or Failed
.
If your integration subscribes to the onPaymentCompleted
and possibly the
onPaymentFailed
event, no redirect or use of the completeUrl
will take
place. But if you do not have any event handler for the onPaymentCompleted
event, the Swedbank Pay JavaScript will perform an HTTP redirect in the top
frame to the completeUrl
. You will still need to do a GET
request on the
payment resource to find the final status (Completed
or Failed
).
View Payment Order
The view-paymentorder
operation contains the URI of the JavaScript that needs
to be set as a script
element’s src
attribute, either client-side through
JavaScript or server-side in HTML as shown below.
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
<!DOCTYPE html>
<html>
<head>
<title>Swedbank Pay Checkout is Awesome!</title>
</head>
<body>
<div id="checkout"></div>
<script src="https://ecom.externalintegration.payex.com/paymentmenu/core/scripts/client/px.paymentmenu.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119&culture=nb-NO"></script>
<script language="javascript">
payex.hostedView.paymentMenu({
container: 'checkout',
culture: 'nb-NO',
onPaymentCompleted: function(paymentCompletedEvent) {
console.log(paymentCompletedEvent);
},
onPaymentFailed: function(paymentFailedEvent) {
console.log(paymentFailedEvent);
},
onPaymentCreated: function(paymentCreatedEvent) {
console.log(paymentCreatedEvent);
},
onPaymentToS: function(paymentToSEvent) {
console.log(paymentToSEvent);
},
onPaymentMenuInstrumentSelected: function(paymentMenuInstrumentSelectedEvent) {
console.log(paymentMenuInstrumentSelectedEvent);
},
onError: function(error) {
console.error(error);
},
}).open();
</script>
</body>
</html>
Update Order
The UpdateOrder
operation is used when there is a change in the amount, vat
amount or there are added or removed order items in the payment order.
If you implement
UpdateOrder
you need to refresh()
the Payment Menu frontend after you have
called the UpdateOrder
API from the backend.
In case the shopping cart is changed in another browser tab, that should also
lead to an UpdateOrder
. On window.onfocus
in the tab that had Payment Menu
initialized, refresh()
should be invoked so the correct amount is authorized.
If the page is refreshed by a full page reload, refresh()
is not necessary.
Request
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
PATCH /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce HTTP/1.1
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"paymentorder": {
"operation": "UpdateOrder",
"amount": 1500,
"vatAmount": 375,
"orderItems": [
{
"reference": "P1",
"name": "Product1",
"type": "PRODUCT",
"class": "ProductGroup1",
"itemUrl": "https://example.com/shop/products/1234",
"imageUrl": "https://example.com/products/product1.jpg",
"description": "Product description",
"discountDescription": "Volume discount",
"quantity": 351.3514,
"quantityUnit": "pcs",
"unitPrice": 300,
"discountPrice": 200,
"vatPercent": 2500,
"amount": 1000,
"vatAmount": 250
},
{
"reference": "P2",
"name": "Product2",
"type": "PRODUCT",
"class": "ProductGroup1",
"description": "Product description",
"quantity": 9876.1531,
"quantityUnit": "pcs",
"unitPrice": 500,
"vatPercent": 2500,
"amount": 500,
"vatAmount": 125
}
]
}
}
Required | Field | Type | Description |
---|---|---|---|
check | paymentorder |
object |
The payment order object. |
check | └➔ operation
|
string |
The operation that the payment order is supposed to perform. |
check | └➔ 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. |
check | └➔ 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. |
check | └➔ description
|
string |
The description of the payment order. |
check | └➔ orderItems
|
array |
The array of items being purchased with the order. Used to print on invoices if the payer chooses to pay with invoice, among other things. orderItems is required in all requests. In capture requests it should only contain the items to be captured from the order. |
check | └─➔ reference
|
string |
A reference that identifies the order item. |
check | └─➔ name
|
string |
The name of the order item. |
check | └─➔ type
|
enum |
PRODUCT , SERVICE , SHIPPING_FEE , PAYMENT_FEE , DISCOUNT , VALUE_CODE or OTHER . The type of the order item. |
check | └─➔ class
|
string |
The classification of the order item. Can be used for assigning the order item to a specific product category, such as MobilePhone . Note that class cannot contain spaces and must follow the regex pattern [\w-]* . Swedbank Pay may use this field for statistics. |
check | └─➔ itemUrl
|
string |
The URL to a page that can display the purchased item, product or similar. |
check | └─➔ imageUrl
|
string |
The URL to an image of the order item. |
check | └─➔ description
|
string |
The human readable description of the order item. |
check | └─➔ discountDescription
|
string |
The human readable description of the possible discount. |
check | └─➔ quantity
|
integer |
The 4 decimal precision quantity of order items being purchased. |
check | └─➔ quantityUnit
|
string |
The unit of the quantity, such as pcs , grams , or similar. This is used for your own book keeping. |
check | └─➔ unitPrice
|
integer |
The price per unit of order item, including VAT. |
check | └─➔ discountPrice
|
integer |
If the order item is purchased at a discounted price. This field should contain that price, including VAT. |
check | └─➔ vatPercent
|
integer |
The percent value of the VAT multiplied by 100, so 25% becomes 2500 . |
check | └─➔ amount
|
integer |
The total amount including VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 500 0 equals 50.00 NOK . |
check | └─➔ vatAmount
|
integer |
The total amount of VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 500 0 equals 50.00 NOK . |
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
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
HTTP/1.1 200 OK
Content-Type: application/json
{
"paymentorder": {
"id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"created": "2018-09-14T13:21:29.3182115Z",
"updated": "2018-09-14T13:21:57.6627579Z",
"operation": "Purchase",
"state": "Ready",
"currency": "SEK",
"amount": 1500,
"vatAmount": 0,
"remainingCaptureAmount": 1500,
"remainingCancellationAmount": 1500,
"remainingReversalAmount": 0,
"description": "Test Purchase",
"initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
"userAgent": "Mozilla/5.0...",
"language": "nb-NO",
"urls" : { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/urls" },
"payeeInfo" : { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payeeinfo" },
"settings": { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/settings" },
"payers": { "id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers"
"orderItems" : { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/orderItems" },
"metadata": { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/metadata" },
"payments": { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payments" },
"currentPayment": { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/currentpayment" }
},
"operations": [
{
"method": "PATCH",
"href": "https://api.stage.payex.com/psp/paymentorders/7f27f445-cefe-4a48-d405-08d8143ed22b",
"rel": "update-paymentorder-updateorder",
"contentType": "application/json"
},
{
"method": "PATCH",
"href": "https://api.externalintegration.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"rel": "update-paymentorder-abort",
"contentType": "application/json"
},
{
"method": "PATCH",
"href": "https://api.externalintegration.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"rel": "update-paymentorder-expandinstrument",
"contentType": "application/json"
},
{
"method": "GET",
"href": "https://ecom.externalintegration.payex.com/paymentmenu/5a17c24e-d459-4567-bbad-aa0f17a76119",
"rel": "redirect-paymentorder",
"contentType": "text/html"
},
{
"method": "GET",
"href": "https://ecom.externalintegration.payex.com/paymentmenu/core/scripts/client/px.paymentmenu.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119&culture=nb-NO",
"rel": "view-paymentorder",
"contentType": "application/javascript"
}
]
}
Field | Type | Description |
---|---|---|
payment |
object |
The payment object contains information about the specific payment. |
└➔ id
|
string |
The relative URI and unique identifier of the payment resource this urls belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ number
|
integer |
The payment number , useful when there’s need to reference the payment in human communication. Not usable for programmatic identification of the payment, for that id should be used instead. |
└➔ created
|
string |
The ISO-8601 date of when the payment was created. |
└➔ updated
|
string |
The ISO-8601 date of when the payment was updated. |
└➔ state
|
string |
Ready , Pending , Failed or Aborted . Indicates the state of the payment, not the state of any transactions performed on the payment. To find the state of the payment’s transactions (such as a successful authorization), see the transactions resource or the different specialized type-specific resources such as authorizations or sales . |
└➔ prices
|
object |
The prices resource lists the prices related to a specific payment. |
└─➔ id
|
string |
The relative URI and unique identifier of the prices resource this urls belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ 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. |
└➔ remainingCaptureAmount
|
integer |
The available amount to capture. |
└➔ remainingCancelAmount
|
integer |
The available amount to cancel. |
└➔ remainingReversalAmount
|
integer |
The available amount to reverse. |
└➔ description
|
string(40) |
A 40 character length textual description of the purchase. |
└➔ userAgent
|
string |
The user agent string of the payer’s browser. |
└➔ language
|
string |
sv-SE , nb-NO or en-US . |
└➔ urls
|
string |
The URI to the urls resource where all URIs related to the payment can be retrieved. |
└➔ payeeInfo
|
string |
The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details. |
└➔ payers
|
string |
The URI to the payer resource where the information about the payer can be retrieved. |
operations |
array |
The array of possible operations to perform |
└─➔ method
|
string |
The HTTP method to use when performing the operation. |
└─➔ href
|
string |
The target URI to perform the operation against. |
└─➔ rel
|
string |
The name of the relation the operation has to the current resource. |
The response given when changing a payment order is equivalent to a GET
request towards the paymentorders
resource,
as displayed above. Even though the fields are the
same, the UpdateOrder
request will overwrite the fields thart were sent in
the initial Purchase
request.
Abort
To abort a payment order, perform the update-paymentorder-abort
operation that
is returned in the payment order response. You need to include the following
in the request body:
Request
1
2
3
4
5
6
7
8
9
10
11
PATCH /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"paymentorder": {
"operation": "Abort",
"abortReason": "CancelledByConsumer"
}
}
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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
HTTP/1.1 200 OK
Content-Type: application/json
{
"paymentorder": {
"id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"created": "2018-09-14T13:21:29.3182115Z",
"updated": "2018-09-14T13:21:57.6627579Z",
"operation": "Purchase",
"state": "Ready",
"currency": "SEK",
"amount": 1500,
"vatAmount": 0,
"remainingCaptureAmount": 1500,
"remainingCancellationAmount": 1500,
"remainingReversalAmount": 0,
"description": "Test Purchase",
"initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
"userAgent": "Mozilla/5.0...",
"language": "nb-NO",
"urls" : { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/urls" },
"payeeInfo" : { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payeeinfo" },
"settings": { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/settings" },
"payers": { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payers" },
"orderItems" : { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/orderItems" },
"metadata": { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/metadata" },
"payments": { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payments" },
"currentPayment": { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/currentpayment" }
},
"operations": [
{
"method": "PATCH",
"href": "https://api.externalintegration.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"rel": "update-paymentorder-abort",
"contentType": "application/json"
},
{
"method": "GET",
"href": "https://ecom.externalintegration.payex.com/paymentmenu/5a17c24e-d459-4567-bbad-aa0f17a76119",
"rel": "redirect-paymentorder",
"contentType": "text/html"
},
{
"method": "GET",
"href": "https://ecom.externalintegration.payex.com/paymentmenu/core/scripts/client/px.paymentmenu.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119&culture=nb-NO",
"rel": "view-paymentorder",
"contentType": "application/javascript"
}
]
}
The response given when aborting a payment order is equivalent to a GET
request towards the paymentorders
resource, as displayed above.
with its state
set to Aborted
.
Cancel
If we want to cancel up to the total authorized (not captured) amount, we need
to perform create-paymentorder-cancel
against the accompanying href
returned
in the operations
list. See the abbreviated request and response below:
Request
1
2
3
4
5
6
7
8
9
10
11
POST /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/cancellations HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"transaction": {
"payeeReference": "ABC123",
"description": "Cancelling parts of the total amount"
}
}
Required | Field | Type | Description |
---|---|---|---|
check | transaction |
object |
The transaction object. |
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. |
check | └➔ description
|
string |
A textual description of why the transaction is cancelled. |
If the cancellation request succeeds, the response should be similar to the example below:
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"cancellation": {
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"transaction": {
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"type": "Cancel",
"state": "Completed",
"amount": 5610,
"vatAmount": 1122,
"description": "Cancelling parts of the authorized payment",
"payeeReference": "AB832"
}
}
}
Property | Type | Description |
---|---|---|
payment |
string |
The relative URI of the payment this cancellation transaction belongs to. |
cancellation |
object |
The cancellation object, containing information about the cancellation transaction. |
└➔ id
|
string |
The relative URI of the cancellation transaction. |
└➔ transaction
|
object |
The transaction object, containing information about the current transaction. |
└─➔ 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 |
Initialized , Completed or Failed . Indicates the state of the transaction. |
└─➔ 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, for that 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 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. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined. |
Reversal
If we want to reverse a previously captured amount, we need to perform
create-paymentorder-reversal
against the accompanying href
returned in the
operations
list. See the abbreviated request and response below:
Request
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
POST /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/reversals HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"transaction": {
"description": "Reversal of captured transaction",
"amount": 1500,
"vatAmount": 375,
"payeeReference": "ABC123",
"receiptReference": "ABC122",
"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
}
]
}
}
Required | Field | Type | Description |
---|---|---|---|
check | transaction |
object |
The transaction object. |
check | └➔ 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. |
check | └➔ 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. |
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. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined. |
└➔ receiptReference
|
string(30) |
A unique reference from the merchant system. It is used to supplement payeeReference as an additional receipt number. |
|
check | └➔ description
|
string |
Textual description of why the transaction is reversed. |
check | └➔ orderItems
|
array |
The array of items being purchased with the order. Used to print on invoices if the payer chooses to pay with invoice, among other things. orderItems is required in all requests. In capture requests it should only contain the items to be captured from the order. |
check | └─➔ reference
|
string |
A reference that identifies the order item. |
check | └─➔ name
|
string |
The name of the order item. |
check | └─➔ type
|
enum |
PRODUCT , SERVICE , SHIPPING_FEE , PAYMENT_FEE , DISCOUNT , VALUE_CODE or OTHER . The type of the order item. |
check | └─➔ class
|
string |
The classification of the order item. Can be used for assigning the order item to a specific product category, such as MobilePhone . Note that class cannot contain spaces and must follow the regex pattern [\w-]* . Swedbank Pay may use this field for statistics. |
└─➔ itemUrl
|
string |
The URL to a page that can display the purchased item, product or similar. | |
└─➔ imageUrl
|
string |
The URL to an image of the order item. | |
└─➔ description
|
string |
The human readable description of the order item. | |
└─➔ discountDescription
|
string |
The human readable description of the possible discount. | |
check | └─➔ quantity
|
integer |
The 4 decimal precision quantity of order items being purchased. |
check | └─➔ quantityUnit
|
string |
The unit of the quantity, such as pcs , grams , or similar. This is used for your own book keeping. |
check | └─➔ unitPrice
|
integer |
The price per unit of order item, including VAT. |
└─➔ discountPrice
|
integer |
If the order item is purchased at a discounted price. This field should contain that price, including VAT. | |
check | └─➔ vatPercent
|
integer |
The percent value of the VAT multiplied by 100, so 25% becomes 2500 . |
check | └─➔ amount
|
integer |
The total amount including VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 SEK and 5000 equals 50.00 SEK . |
check | └─➔ vatAmount
|
integer |
The total amount of VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 SEK and 5000 equals 50.00 SEK . |
If the reversal request succeeds, the response should be similar to the example below:
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment": "/psp/paymentorders/payments/09ccd29a-7c4f-4752-9396-12100cbfecce",
"reversal": {
"id": "/psp/paymentorders/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/cancellations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"transaction": {
"id": "/psp/paymentorders/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"type": "Reversal",
"state": "Completed",
"amount": 15610,
"vatAmount": 3122,
"description": "Reversing the capture amount",
"payeeReference": "ABC987",
"receiptReference": "ABC986"
}
}
}
Property | Type | Description |
---|---|---|
payment |
string |
The relative URI of the payment this reversal transaction belongs to. |
reversals |
object |
The reversal object, containing information about the reversal transaction. |
└➔ id
|
string |
The relative URI of the reversal transaction. |
└➔ transaction
|
object |
The transaction object, containing information about the current transaction. |
└─➔ 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 authorization 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 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. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined. |
└➔ receiptReference
|
string(30) |
A unique reference from the merchant system. It is used to supplement payeeReference as an additional receipt number. |
Transactions
A payment order contains one or more payment
sub-resources, which in turn
contains sub-resources in the form of transactions
.
Most operations performed on a payment ends up as a transaction
resource. The
different types of operations that alter the state of the payment by creating a
transaction is described below.
The transactions
resource will list the transactions (one or more) on a
specific payment.
Request
1
2
3
4
GET /psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
The transaction
resource contains information about the
transaction
transaction made against a paymentorders payment. You can
return a specific transaction
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/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"transactions": {
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions",
"transactionList": [{
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"transaction": {
"id": "/psp/paymentorders/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": "Transaction",
"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 transactions belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
transactions |
object |
The current transactions resource. |
└➔ id
|
string |
The relative URI and unique identifier of the transactions resource this transactions belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ transactionList
|
array |
The array of transaction transaction objects. |
└➔ transactionList[]
|
object |
The transaction transaction object described in the transaction resource below. |
└─➔ id
|
string |
The relative URI and unique identifier of the transaction resource this transactions 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 transaction 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. |
Transaction
The transaction
resource contains the generic details of a transaction on a
specific payment.
When a transaction is created it will have one of three states:
-
Initialized
- if there is some error where the source is undeterminable (network failure, etc), the transaction will remain Initialized. The corresponding state of the payment order will in this case be set to pending. No further transactions can be created. -
Completed
- if everything went ok the transaction will follow through to completion. -
Failed
- if the transaction has failed (i.e. a denial from the acquiring bank) it is possible to retry (i.e the payer tries using another card) up to a maximum amount of retries (in that case which the payment order gets the statefailed
as well).
Request
1
2
3
4
GET /psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"transaction": {
"id": "/psp/paymentorders/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": "Initialized",
"number": 1234567890,
"amount": 1000,
"vatAmount": 250,
"description": "Test transaction",
"payeeReference": "AH123456",
"failedReason": "",
"isOperational": true,
"operations": []
}
}
Transaction Problems
In the event that a transaction is failed
, the transaction
response will
contain a problem
property as seen in the example below. To view all the
problems that can occur due to an unsuccesful transaction, head over to the
problems section.
The created transaction
resource contains information about the
transaction
transaction made against a paymentorders
payment.
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
27
28
29
30
31
32
33
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"transaction": {
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"itemDescriptions": {
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
},
"transaction": {
"id": "/psp/paymentorders/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": "Transaction",
"state": "Failed",
"number": 1234567890,
"amount": 1000,
"vatAmount": 250,
"description": "Test transaction",
"payeeReference": "AH123456",
"isOperational": false,
"problem": {
"type": "https://api.payex.com/psp/errordetail/paymentorders/3DSECUREERROR",
"title": "Error when complete authorization",
"status": 400,
"detail": "Unable to complete 3DSecure verification!",
"problems": [
]
}
}
}
Field | Type | Description | |
---|---|---|---|
payment |
string |
The relative URI and unique identifier of the payment resource this transaction belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
transaction |
string |
The current transaction transaction resource. |
|
└➔ id
|
string |
The relative URI and unique identifier of the transaction resource this transaction belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
└➔ itemDescriptions
|
object |
The object representation of the itemDescriptions resource. |
|
└─➔ id
|
string |
The relative URI and unique identifier of the itemDescriptions resource this transaction belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
└➔ transaction
|
object |
The object representation of the generic transaction resource. | |
└─➔ id
|
string |
The relative URI and unique identifier of the transaction resource this transaction 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 transaction 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. |
|
└─➔ receiptReference
|
string |
A unique reference for the transaction. This reference is used as an invoice/receipt number. | |
└─➔ failedReason
|
string |
The human readable explanation of why the payment failed. | |
└─➔ 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. |
Recurring Payments
If you want to enable subsequent recurring – server-to-server – payments, you need to create a recurrence token. This token will be utilized after the initial payment order. Recurring payments must be activated on the contract with Swedbank Pay in order to work.
Recurrence Token
- When initiating a
Purchase
payment order, you need to make sure that the fieldgenerateRecurrenceToken
is set totrue
. This recurrence token will stored in the authorization transaction sub-resource on the underlying payment resource. - When initiating a
Verify
payment order, a recurrence token will be generated automatically. This recurrence token is stored in the verification sub-resource on the underlying payment resource.
You can view the current payment resource, containg the recurrence token and
other payment instrument properties, by expanding the sub-resource
currentpayment
when doing a GET
request on the
paymentorders
resource.
Request
1
2
GET /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce?$expand=currentpayment HTTP/1.1
Host: api.externalintegration.payex.com
Delete recurrenceToken
Payers should be able to delete payment tokens that are associated to
them. How to delete a recurrenceToken
is described in the example below.
Note that the value of state
must be Deleted
when deleting the token.
No other states are supported.
Request
1
2
3
4
5
6
7
8
9
PATCH /psp/paymentorders/recurrenceTokens/5a17c24e-d459-4567-bbad-aa0f17a76119 HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"state": "Deleted",
"comment": "Comment on why the deletion is happening"
}
Response
1
2
3
4
5
6
7
8
HTTP/1.1 200 OK
Content-Type: application/json
{
"token": "5a17c24e-d459-4567-bbad-aa0f17a76119",
"isDeleted": true
}
Creating Recurring Payments
When you have a recurrenceToken
token safely tucked away, you can use this
token in a subsequent Recur
payment order. This will be a server-to-server
affair, as we have tied all necessary payment instrument details related to the
recurrence token during the initial payment order.
Request
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
POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"paymentorder": {
"operation": "Recur",
"recurrenceToken": "09ccd29a-7c4f-4752-9396-12100cbfecce",
"currency": "SEK",
"amount": 1000,
"vatAmount": 250,
"description": "Test Purchase",
"userAgent": "Mozilla/5.0...",
"language": "sv-SE",
"urls": {
"callbackUrl": "https://example.com/callback"
},
"payeeInfo": {
"payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
"payeeReference": "CD1234",
"payeeName": "Merchant1",
"productCategory": "A123",
"orderReference": "or-12456",
"subsite": "Subsite1"
},
"orderItems": [
{
"reference": "P1",
"name": "Product1",
"type": "PRODUCT",
"class": "ProductGroup1",
"itemUrl": "https://example.com/shop/id=123",
"imageUrl": "https://example.com/product1.jpg",
"description": "Product 1 description",
"discountDescription": "Volume discount",
"quantity": 4,
"quantityUnit": "pcs",
"unitPrice": 300,
"discountPrice": 200,
"vatPercent": 2500,
"amount": 1000,
"vatAmount": 250
}
]
"metadata": {
"key1": "value1",
"key2": 2,
"key3": 3.1,
"key4": false
}
}
}
Required | Field | Type | Description |
---|---|---|---|
check | paymentorder |
object |
The payment order object. |
check | operation |
object |
Recur . |
check | └➔ recurrenceToken
|
string |
The created recurrenceToken, if operation: Verify , operation: Recur or generateRecurrenceToken: true was used. |
check | └➔ currency
|
string |
The currency of the payment order. |
check | └➔ 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. |
check | └➔ 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. |
check | └➔ description
|
string |
A 40 character length textual description of the purchase. |
check | └─➔ userAgent
|
string |
The User-Agent string of the payer’s web browser. |
check | └─➔ language
|
string |
sv-SE , nb-NO or en-US . |
check | └─➔ urls
|
string |
The URI to the urls resource where all URIs related to the payment order can be retrieved. |
check | └─➔ callbackUrl
|
string |
The URL that Swedbank Pay will perform an HTTP POST against every time a transaction is created on the payment. See callback for details. |
check | └➔ payeeInfo
|
string |
The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details. |
check | └─➔ payeeId
|
string |
This is the unique id that identifies this payee (like merchant) set by Swedbank Pay. |
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. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined. |
└➔ receiptReference
|
string(30) |
A unique reference from the merchant system. It is used to supplement payeeReference as an additional receipt number. |
|
check | └─➔ payeeName
|
string |
The payee name (like merchant name) that will be displayed when redirected to Swedbank Pay. |
check | └─➔ productCategory
|
string |
A product category or number sent in from the payee/merchant. This is not validated by Swedbank Pay, but will be passed through the payment process and may be used in the settlement process. |
check | └─➔ orderReference
|
String(50) |
The order reference should reflect the order reference found in the merchant’s systems. |
check | └─➔ subsite
|
String(40) |
The subsite field can be used to perform split settlement on the payment. The subsites must be resolved with Swedbank Pay reconciliation before being used. |
check | └➔ orderItems
|
array |
The array of items being purchased with the order. Used to print on invoices if the payer chooses to pay with invoice, among other things. orderItems is required in all requests. In capture requests it should only contain the items to be captured from the order. |
check | └─➔ reference
|
string |
A reference that identifies the order item. |
check | └─➔ type
|
enum |
PRODUCT , SERVICE , SHIPPING_FEE , PAYMENT_FEE , DISCOUNT , VALUE_CODE or OTHER . The type of the order item. |
check | └─➔ class
|
string |
The classification of the order item. Can be used for assigning the order item to a specific product category, such as MobilePhone . Note that class cannot contain spaces and must follow the regex pattern [\w-]* . Swedbank Pay may use this field for statistics. |
└─➔ itemUrl
|
string |
The URL to a page that can display the purchased item, product or similar. | |
︎︎︎ | └─➔ imageUrl
|
string |
The URL to an image of the order item. |
└─➔ description
|
string |
The human readable description of the order item. | |
└─➔ discountDescription
|
string |
The human readable description of the possible discount. | |
check | └─➔ quantity
|
integer |
The 4 decimal precision quantity of order items being purchased. |
check | └─➔ quantityUnit
|
string |
The unit of the quantity, such as pcs , grams , or similar. This |
is used for your own book keeping. | |||
check | └─➔ unitPrice
|
integer |
The price per unit of order item, including VAT. |
check | └─➔ discountPrice
|
integer |
If the order item is purchased at a discounted price. This field should contain that price, including VAT. |
check | └─➔ vatPercent
|
integer |
The percent value of the VAT multiplied by 100, so 25% becomes 2500 . |
check | └─➔ amount
|
integer |
The total amount including VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 SEK and 5000 equals 50.00 SEK . |
check | └─➔ vatAmount
|
integer |
The total amount of VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 SEK and 5000 equals 50.00 SEK . |
└➔ metadata
|
object |
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. |
|
MOTO
This feature is only available for merchants who have a specific agreement with Swedbank Pay.
MOTO (Mail Order / Telephone Order) is a purchase where you, as a merchant, enter the payer’s card details in order to make a payment. The card details are provided by the payer to the sales representative over telephone or in writing, who in turn enters them into the payment interface.
Common use cases are travel or hotel bookings, where the payer calls the sales
representative to make a booking. This feature is only supported in the
Purchase
operation. See the abbreviated example below on how to implement MOTO
by setting the generateMotoPayment
to true
.
Request
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
POST /psp/paymentorders/payments HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"paymentorder": {
"operation": "Purchase",
"intent": "Authorization",
"generateMotoPayment": true,
"currency": "NOK",
"amount": 1500,
"vatAmount": 0,
"description": "Test Moto",
"userAgent": "Mozilla/5.0...",
"language": "nb-NO",
"urls": {
"callbackUrl": "https://example.com/payment-callback"
},
"payeeInfo": {
"payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
"payeeReference": "CD1234",
"payeeName": "Merchant1",
"productCategory": "A123",
"orderReference": "or-12456",
"subsite": "MySubsite"
}
}
}
To authorize the payment, find the operation with rel
equal to
redirect-paymentorder
in the response and redirect the merchant
employee to the provided href
to fill out the payer’s card details. You will
find an abbreviated example of the response provided below.
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
27
28
29
30
31
32
33
34
35
36
37
38
39
HTTP/1.1 200 OK
Content-Type: application/json
{
"paymentorder": {
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"number": 1234567890,
"created": "2016-09-14T13:21:29.3182115Z",
"updated": "2016-09-14T13:21:57.6627579Z",
"state": "Ready",
"operation": "Purchase",
"intent": "Authorization",
"currency": "NOK",
"amount": 1500,
"remainingCaptureAmount": 1500,
"remainingCancellationAmount": 1500,
"remainingReversalAmount": 0,
"description": "Test Moto",
"initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
"userAgent": "Mozilla/5.0...",
"language": "nb-NO",
"prices": { "id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices" },
"transactions": { "id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions" },
"authorizations": { "id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations" },
"captures": { "id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures" },
"reversals": { "id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals" },
"cancellations": { "id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations" },
"urls" : { "id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls" },
"payeeInfo" : { "id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo" }
},
"operations": [
{
"rel": "redirect-paymentorder",
"href": "https://ecom.externalintegration.payex.com/paymentmenu/5a17c24e-d459-4567-bbad-aa0f17a76119",
"method": "GET",
"contentType": "text/html"
}
]
}
Purchase Flow
sequenceDiagram
participant Consumer
participant ConsumerSubscription
participant Merchant
participant SwedbankPay as Swedbank Pay
rect rgba(81,43,43,0.1)
note left of Consumer: Checkin
activate Consumer
Consumer ->>+ SwedbankPay: Checkin procedure
deactivate Consumer
end
rect rgba(55, 91, 134,0.1)
activate Consumer
note left of Consumer: Payment Menu
Consumer ->>+ Merchant: Initiate Purchase
deactivate Consumer
Merchant ->>+ SwedbankPay: POST/psp/paymentorders (generateRecurrenceToken = True)
deactivate Merchant
SwedbankPay -->>+ Merchant: rel:view-paymentorder
deactivate SwedbankPay
Merchant -->>- Consumer: Display Payment Menu on Merchant Page
activate Consumer
Consumer ->> Consumer: Initiate Payment Menu Hosted View (open iframe)
Consumer -->>+ SwedbankPay: Show Payment UI page in iframe
deactivate Consumer
SwedbankPay ->>+ Consumer: Do payment logic
deactivate SwedbankPay
SwedbankPay -->>+ Merchant: POST Payment Callback
SwedbankPay -->>- Payer: Payment Status
Payer -->>+ Merchant: Redirect to Payment Complete URL
Merchant ->>+ SwedbankPay: GET/psp/paymentorders/<paymentOrderId>
SwedbankPay -->>+ Merchant: Payment Order Status
end
rect rgba(63, 204, 164,0.1)
note left of Payer: Capture
activate Merchant
Merchant ->>+ SwedbankPay: POST/psp/paymentorders/<paymentOrderId>/captures
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>PaymentInstruments that support <br>Authorizations.
end
rect rgba(94, 108, 23,0.1)
note left of Payer: Recurring payment
activate ConsumerSubscription
ConsumerSubscription ->>+ Merchant: Start recurring payment
deactivate ConsumerSubscription
note left of Merchant: Server-to-Server request at a later date
activate Merchant
Merchant ->>+ SwedbankPay: POST Card Payments (operation=RECUR) (reccurenceToken included)
deactivate Merchant
SwedbankPay -->>- Merchant: Payment resource
opt [Intent=Authorization]
Merchant ->>+ SwedbankPay: Create-capture
SwedbankPay -->>- Merchant: Transaction resource
end
activate Merchant
Merchant -->>- ConsumerSubscription: display purchase result
end
Purchase Payments
The Purchase
operation is used in all common purchase scenarios.
Purchase
1
2
3
4
5
{
"paymentorder": {
"operation": "Purchase"
{
}
Verify Payments
The Verify
operation lets you post verifications to confirm the validity of
credit card information, without reserving or charging any amount. This
option is mainly used to initiate a recurring payment scenario where the card
will be charged at a later date. The request body is equivalent to a Purchase
order with credit card as the selected item.
A recurrence token will be generated automatically,
rendering the parameter generateRecurrenceToken
unnecessary for this
operation.
Verify
1
2
3
4
5
{
"paymentorder": {
"operation": "Verify"
{
}
Request
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
POST /psp/paymentorders/payments HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"paymentorder": {
"operation": "Verify",
"currency": "NOK",
"description": "Test Verification",
"userAgent": "Mozilla/5.0...",
"language": "nb-NO",
"generatePaymentToken": true,
"generateRecurrenceToken": true,
"urls": {
"hostUrls": ["https://example.com", "https://example.net"],
"completeUrl": "https://example.com/payment-completed",
"cancelUrl": "https://example.com/payment-canceled",
"logoUrl": "https://example.com/payment-logo.png",
"termsOfServiceUrl": "https://example.com/payment-terms.html"
},
"payeeInfo": {
"payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
"payeeReference": "CD1234",
"payeeName": "Merchant1",
"productCategory": "A123",
"orderReference": "or-12456",
"subsite": "MySubsite"
},
"payer": {
"payerReference": "AB1234",
}
},
"creditCard": {
"rejectCreditCards": false,
"rejectDebitCards": false,
"rejectConsumerCards": false,
"rejectCorporateCards": false
}
}
Required | Field | Type | Description | |
---|---|---|---|---|
check | paymentorder |
object |
The payment order object. | |
check | └➔ operation
|
string |
The operation that the payment order is supposed to perform. | |
check | └➔ currency
|
string |
The currency of the payment. | |
check | └➔ 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. |
|
check | └➔ 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. |
|
check | └➔ description
|
string |
The description of the payment order. | |
check | └➔ generatePaymentToken
|
bool |
true or false . Set this to true if you want to create a payment token for future use as One Click Payments. All payment instruments will still be availabe in the payment menu, but the payment token will only be generated if the instrument chosen by the payer supports one click. |
|
check | └➔ userAgent
|
string |
The user agent of the payer. | |
check | └➔ language
|
string |
The language of the payer. | |
check | └➔ generateRecurrenceToken
|
bool |
Determines whether a recurrence token should be generated. A recurrence token is primarily used to enable future recurring payments – with the same token – through server-to-server calls. Default value is false . If set to true , only payment instruments which support recurring payments will be visible in the payment menu. |
|
check | └➔ urls
|
object |
The urls object, containing the URLs relevant for the payment order. |
|
check | └─➔ hostUrls
|
array |
The array of URIs valid for embedding of Swedbank Pay Hosted Views. | |
check | └─➔ completeUrl
|
string |
The URL that Swedbank Pay will redirect back to when the payer has completed his or her 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 |
The URI to redirect the payer to if the payment is canceled, either by the payer or by the merchant trough an abort request of the payment or paymentorder . |
||
└─➔ paymentUrl
|
string |
The URI that Swedbank Pay will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. See paymentUrl for details. |
||
check | └─➔ callbackUrl
|
string |
The URI to the API endpoint receiving POST requests on transaction activity related to the payment order. |
|
check | └─➔ termsOfServiceUrl
|
string |
The URI to the terms of service document the payer must accept in order to complete the payment. Note that this field is not required unless generateReferenceToken or generateRecurrenceToken is also submitted in the request. This is the Merchants, not the Swedbank Pay Terms of Service. HTTPS is a requirement. |
|
check | └➔ payeeInfo
|
string |
The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details. |
|
check | └─➔ payeeId
|
string |
The ID of the payee, usually the merchant ID. | |
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. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined. |
|
└─➔ payeeName
|
string |
The name of the payee, usually the name of the merchant. | ||
└─➔ productCategory
|
string |
A product category or number sent in from the payee/merchant. This is not validated by Swedbank Pay, but will be passed through the payment process and may be used in the settlement process. | ||
└─➔ orderReference
|
string(50) |
The order reference should reflect the order reference found in the merchant’s systems. | ||
└─➔ subsite
|
String(40) |
The subsite field can be used to perform split settlement on the payment. The subsites must be resolved with Swedbank Pay reconciliation before being used. | ||
└➔ payer
|
string |
The payer object, containing information about the payer. |
||
└─➔ payerReference
|
string |
The reference to the payer from the merchant system, like e-mail address, mobile number, customer number etc. Also used in Payer Aware Payment Menu. Mandatory if generateReccurenceToken , RecurrenceToken , generatePaymentToken or paymentToken is true . |
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
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
HTTP/1.1 200 OK
Content-Type: application/json
{
"paymentorder": {
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"paymentToken" : "5a17c24e-d459-4567-bbad-aa0f17a76119",
"number": 1234567890,
"created": "2016-09-14T13:21:29.3182115Z",
"updated": "2016-09-14T13:21:57.6627579Z",
"operation": "Verify",
"state": "Ready",
"currency": "NOK",
"amount": 0,
"description": "Test Verification",
"initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
"userAgent": "Mozilla/5.0",
"language": "nb-NO",
"transactions": { "id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions" },
"verifications": { "id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/verifications" },
"urls" : { "id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls" },
"payeeInfo" : { "id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo" },
"payers" : { "id": "/psp/paymentorders/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/payers" },
"settings": { "id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/settings" }
},
"operations": [
{
"href": "https://api.externalintegration.payex.com/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"rel": "update-payment-abort",
"method": "PATCH",
"contentType": "application/json"
},
{
"href": "https://ecom.externalintegration.payex.com/paymentorders/payments/verification/5a17c24e-d459-4567-bbad-aa0f17a76119",
"rel": "redirect-verification",
"method": "GET",
"contentType": "application/json"
},
{
"method": "GET",
"href": "https://ecom.externalintegration.payex.com/paymentorders/core/scripts/client/px.paymentorders.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119",
"rel": "view-verification",
"contentType": "application/javascript"
},
{
"method": "POST",
"href": "https://ecom.externalintegration.payex.com/psp/paymentorders/confined/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/verifications",
"rel": "direct-verification",
"contentType": "application/json"
}
]
}
Field | Data type | Description | |
---|---|---|---|
payment |
object |
The payment object contains information about the retrieved payment. | |
└➔ id
|
string |
The relative URI and unique identifier of the payment resource this transaction belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
└➔ paymentToken
|
string |
The payment token created for the purchase used in the authorization to create One Click Payments. | |
└➔ number
|
integer |
The payment number , useful when there’s need to reference the payment in human communication. Not usable for programmatic identification of the payment, for that id should be used instead. |
|
└➔ created
|
string |
The ISO-8601 date of when the payment was created. | |
└➔ updated
|
string |
The ISO-8601 date of when the payment was updated. | |
└➔ operation
|
string |
Purchase | |
└➔ state
|
string |
Ready , Pending , Failed or Aborted . Indicates the state of the payment. This field is only for status display purposes. |
|
└➔ currency
|
string |
The currency used | |
└➔ description
|
string(40) |
A 40 character length textual description of the purchase. | |
└➔ initiatingSystemUserAgent
|
string |
The system user agent used | |
└➔ userAgent
|
string |
The user agent string of the payer’s browser. | |
└➔ language
|
string |
sv-SE , nb-NO or en-US . |
|
└➔ urls
|
string |
The URI to the urls resource where all URIs related to the payment can be retrieved. |
|
└➔ payeeInfo
|
string |
The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details. |
|
└➔ payers
|
string |
The URI to the payer resource where the information about the payer can be retrieved. |
|
└➔ operations
|
array |
The array of possible operations to perform, given the state of the payment order. See Operations for details. |
Payments Resource
A payment order is able to hold more than one payment object, even though a successful payment order only harbours one successful payment. This is necessary as the payer might select and initiate a payment option that is not followed through successfully. I.e. if the payer cancels an invoice payment, a cancel transaction will still be tied to that particular invoice payment resource. This payment resource will continue to exist, even if the payer successfully should finish the purchase with a card payment instead.
Request
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
GET /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payments HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"paymentorder": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"payments": {
"id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payments",
"paymentList" : [
{
"id": "/psp/creditcard/payments/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"instrument" : "CreditCard",
"created": "2016-09-14T13:21:29.3182115Z"
},
{
"id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"instrument" : "Invoice",
"created": "2016-09-14T13:21:29.3182115Z"
}
]
}
}
Field | Type | Description |
---|---|---|
paymentorder |
object |
The payment order object. |
payments |
object |
The payments object. |
└➔ id
|
string |
The relative URI and unique identifier of the payments resource this transaction belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ paymentList
|
array |
The array of payment objects. |
└─➔ id
|
string |
The relative URI and unique identifier of the payment resource this transaction belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└─➔ instrument
|
string |
The name of the payment instrument. |
└─➔ created
|
string |
The ISO-8601 date and time of when the payment was created. |
Current Payment Resource
The currentpayment
resource displays the payment that are active within the
payment order container.
Request
1
2
3
4
GET /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/currentpayment HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
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
27
28
29
30
31
32
33
34
35
36
37
38
39
HTTP/1.1 200 OK
Content-Type: application/json
{
"paymentorder": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"menuElementName": "paymentorders",
"payment": {
"recurrenceToken": "09ccd29a-7c4f-4752-9396-12100cbfecce",
"id": "/psp/paymentorders/payments/09ccd29a-7c4f-4752-9396-12100cbfecce",
"number": 1234567890,
"instrument": "CreditCard",
"created": "2016-09-14T13:21:29.3182115Z",
"updated": "2016-09-14T13:21:57.6627579Z",
"operation": "Purchase",
"intent": "Authorization",
"state": "Ready",
"currency": "NOK",
"amount": 1500,
"remainingCaptureAmount": 1500,
"remainingCancellationAmount": 1500,
"remainingReversalAmount": 0,
"description": "Test Purchase",
"userAgent": "Mozilla/5.0...",
"language": "nb-NO",
"prices": { "id": "/psp/paymentorders/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/prices" },
"transactions": { "id": "/psp/paymentorders/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/transactions" },
"authorizations": { "id": "/psp/paymentorderspayments/09ccd29a-7c4f-4752-9396-12100cbfecce/authorizations" },
"captures": { "id": "/psp/paymentorders/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/captures" },
"cancellations": { "id": "/psp/paymentorders/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/cancellations" },
"reversals": { "id": "/psp/paymentorders/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/reversals" },
"verifications": { "id": "/psp/paymentorders/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/verifications" },
"urls" : { "id": "/psp/paymentorderspayments/09ccd29a-7c4f-4752-9396-12100cbfecce/urls" },
"payeeInfo" : { "id": "/psp/paymentorders/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/payeeInfo" },
"payers" : { "id": "/psp/paymentorders/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/payers" },
"metadata" : { "id": "/psp/paymentorders/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/metadata" },
"settings": { "id": "/psp/paymentorders/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/settings" }
},
"operations": []
}
Field | Type | Description |
---|---|---|
paymentorder |
string |
The relative URI and unique identifier of the paymentorder resource this payment belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
menuElementName |
string |
creditcard , invoice , etc. The name of the selected menu element. |
payment |
object |
The payment object. |
└➔ recurrenceToken
|
string |
The created recurrenceToken, if operation: Verify or generateRecurrenceToken: true was used. |
└➔ id
|
string |
The relative URI and unique identifier of the payment resource this payment belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ number
|
integer |
The payment number , useful when there’s need to reference the payment in human communication. Not usable for programmatic identification of the payment, for that id should be used instead. |
└➔ instrument
|
string |
The payment instrument used. |
└➔ created
|
string |
The ISO-8601 date of when the payment was created. |
└➔ updated
|
string |
The ISO-8601 date of when the payment was updated. |
└➔ operation
|
string |
Purchase , payout , Verify or recur. The type of the initiated payment. |
└➔ intent
|
string |
The intent of the payment. |
└➔ state
|
string |
Ready , Pending , Failed or Aborted . Indicates the state of the payment. This field is only for status display purposes. |
└➔ currency
|
string |
The currency of the payment. |
└➔ prices
|
object |
The prices object. |
└─➔ 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. |
└─➔ remainingCaptureAmount
|
integer |
The available amount to capture. |
└─➔ remainingCancelAmount
|
integer |
The available amount to cancel. |
└─➔ remainingReversalAmount
|
integer |
The available amount to reverse. |
└➔ description
|
string(40) |
A 40 character length textual description of the purchase. |
└➔ userAgent
|
string |
The user agent string of the payer’s browser. |
└➔ language
|
string |
sv-SE , nb-NO or en-US . |
Prices
The prices
resource lists the prices related to a specific payment. In short,
it is where you enter the payment’s amount. It consists of the payment’s id
and the priceList
, which again contains the payment’s type
, amount
and
vatAmount
.
The type
refers to the payment instrument, like Swish
, Trustly
or
Creditcard
. Read more about the types below the code example and table. The
amount
refers to the full amount (incl. VAT) for the payment, and
vatAmount
indicates how much of the full amount which is VAT.
Request
1
2
3
4
GET /psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices/ HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"prices": {
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices",
"priceList": [
{
"type": "VISA",
"amount": 2350,
"vatAmount": 0
},
{
"type": "MasterCard",
"amount": 2350,
"vatAmount": 0
}
]
}
}
Field | Type | Description |
---|---|---|
payment |
string |
The relative URI and unique identifier of the payment resource this prices belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
prices |
object |
The prices resource. |
└➔ id
|
string |
The relative URI and unique identifier of the prices resource this prices belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ priceList
|
array |
The array of price objects. Note: Even if you specifiy CreditCard in the input message the system will return all your configured card brands instead when you expan the priceList. |
└─➔ type
|
string |
The type of the price object. |
└─➔ 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. |
Prices Object Types
Each payment instrument have one or more prices object types. Usually there is
only one, whichs corresponds with the name of the payment instrument, like
Vipps
, Swish
or Mobilepay
.
The most common occurence of several object types is for card payments. While it
is possible to group them all as Creditcard
, you can also differentiate on
card types as shown in the example above. This is useful if certain card brands
have additional fees, others have discounts or something similar. If you do
differentiate, you need to add all accepted card brands as a separate object
types.
Custom Logo
With permission and activation on your contract, it is possible to replace the
Swedbank Pay logo in the Payment Menu. See the abbreviated example
below with the added logoUrl
in the Payment Order Purchase request.
-
If the configuration is activated and you send in a
logoUrl
, then the SwedbankPay logo is replaced with the logo sent in and the text is changed accordingly. -
If the configuration is activated and you do not send in a
logoUrl
, then no logo and no text is shown. -
If the configuration is deactivated, sending in a
logoUrl
has no effect.
Request
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
POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"paymentorder": {
"operation": "Purchase",
"currency": "SEK",
"amount": 1500,
"vatAmount": 375,
"description": "Test Purchase",
"userAgent": "Mozilla/5.0...",
"language": "sv-SE",
"instrument": "CreditCard"
"generateRecurrenceToken": true,
"generatePaymentToken": true,
"urls": {
"hostUrls": [ "https://example.com", "https://example.net" ],
"completeUrl": "https://example.com/payment-completed",
"cancelUrl": "https://example.com/payment-canceled",
"paymentUrl": "https://example.com/perform-payment",
"callbackUrl": "https://api.example.com/payment-callback",
"termsOfServiceUrl": "https://example.com/termsandconditoons.pdf",
"logoUrl": "https://example.com/logo.png"
}
}
}
Payer Resource
The payer
resource contains payer information related to the payment order.
Request
1
2
3
4
GET /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payers/ HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
HTTP/1.1 200 OK
Content-Type: application/json
{
"paymentorder": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
"payer" : {
"id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payer",
"reference": "reference to payer",
"email": "email",
"msisdn": "msisdn",
"shippingAddress": {
"addressee": "firstName + lastName",
"coAddress": "coAddress",
"streetAddress": "streetAddress",
"zipCode": "zipCode",
"city": "city",
"countryCode": "countryCode"
}
}
}
Field | Type | Description |
---|---|---|
paymentorder |
string |
The relative URI and unique identifier of the paymentorder resource this payer belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
payer |
object |
The payer object. |
└➔ id
|
string |
The relative URI and unique identifier of the payer resource this payer belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ email
|
string |
Payer’s registered email address. The field is related to 3-D Secure 2. |
└➔ msisdn
|
string |
Payer’s registered mobile phone number. The field is related to 3-D Secure 2. |
└➔ shippingAddress
|
object |
The shipping address object related to the payer . |
└─➔ addresse
|
string |
The name of the addressee – the receiver of the shipped goods. |
└─➔ coAddress
|
string |
Payer’ s c/o address, if applicable. |
└─➔ streetAddress
|
string |
Payer’s street address. Maximum 50 characters long. |
└─➔ zipCode
|
string |
Payer’s zip code |
└─➔ city
|
string |
Payer’s city of residence |
└─➔ countryCode
|
string |
Country Code for country of residence. |
Payment Menu Events
During operation in the Payment Menu, several events can occur. They are described below.
Event Overrides
Adding an event handler to one of the following events overrides the default event handler, meaning your custom event handler will have to do what the default event handler did. If you don’t, the behaviour of the event is going to be undefined. Just adding an event handler for logging purposes is therefore not possible, the event handler will have to perform some functionality similar to the event handler you are overriding.
onPaymentPending
This events triggers when a payment enters a paying state ( Sale
, Authorize
,
Cancel
etc). The onPaymentPending
event
will be followed by either onPaymentCompleted
, onPaymentFailed
or
onPaymentTransactionFailed
based on the result of the payment. Read more about
these events below.
onPaymentPending event object
1
2
3
{
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1"
}
Field | Type | Description |
---|---|---|
id |
string |
The relative URI and unique identifier of the payment resource this payer belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
onPaymentCompleted
This event triggers when a payment has completed successfully.
The onPaymentCompleted
event is raised with the following event argument
object:
onPaymentCompleted event object
1
2
3
4
{
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"redirectUrl": "https://example.com/complete"
}
Field | Type | Description |
---|---|---|
id |
string |
The relative URI and unique identifier of the payment resource this payer belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
redirectUrl |
string |
The URI the user will be redirect to after a completed payment. |
onPaymentCanceled
This event triggers when the user cancels the payment.
The onPaymentCanceled
event is raised with the following event argument
object:
onPaymentCanceled event object
1
2
3
4
{
"id": "/psp/paymentorderspayments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"redirectUrl": "https://example.com/canceled"
}
Field | Type | Description |
---|---|---|
id |
string |
The relative URI and unique identifier of the payment resource this payer belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
redirectUrl |
string |
The URI the user will be redirect to after a canceled payment. |
onPaymentFailed
This event triggers when a payment has failed, disabling further attempts to
perform a payment. The onPaymentFailed
event is raised with the following
event argument object:
onPaymentFailed event object
1
2
3
4
{
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"redirectUrl": "https://example.com/failed"
}
Field | Type | Description |
---|---|---|
id |
string |
The relative URI and unique identifier of the payment resource this payer belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
redirectUrl |
string |
The URI the user will be redirect to after a failed payment. |
onPaymentToS
This event triggers when the user clicks on the “Display terms and conditions”
link. The onPaymentToS
event is raised with the following event
argument object:
onPaymentToS event object
1
2
3
4
{
"origin": "owner",
"openUrl": "https://example.com/terms-of-service"
}
Field | Type | Description |
---|---|---|
origin |
string |
owner , merchant . The value is always merchant unless Swedbank Pay hosts the view. |
openUrl |
string |
The URI containing Terms of Service and conditions. |
onError
This event triggers during terminal errors or if the configuration fails
validation. The onError
event will be raised with the following event argument
object:
onError event object
1
2
3
4
5
{
"origin": "paymentorders",
"messageId": "ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"details": "Descriptive text of the error"
}
Field | Type | Description |
---|---|---|
origin |
string |
paymentorders , identifies the system that originated the error. |
messageId |
string |
A unique identifier for the message. |
details |
string |
A human readable and descriptive text of the error. |
onPaymentMenuInstrumentSelected
This event triggers when a user actively changes payment instrument in the
Payment Menu. The onPaymentMenuInstrumentSelected
event is raised with the
following event argument object:
onPaymentMenuInstrumentSelected event object
1
2
3
4
{
"name": "menu identifier",
"instrument": "creditcard | vipps | swish | invoice",
}
Field | Type | Description |
---|---|---|
name |
string |
The name and identifier of specific instrument instances - i.e. if you deploy more than one type of credit card payments, they would be distinguished by name . |
instrument |
string |
Creditcard , vipps , swish , invoice . The instrument selected by the user. |
onPaymentCreated
This event triggers when a user has selected a payment instrument and actively
attempts to perform a payment. The onPaymentCreated
event is raised with the
following event argument object:
onPaymentCreated event object
1
2
3
4
{
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"instrument": "creditcard",
}
Field | Type | Description |
---|---|---|
id |
string |
The relative URI and unique identifier of the payment resource this payer belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
instrument |
string |
Creditcard , vipps , swish , invoice . The instrument selected when initiating the payment. |
onPaymentTransactionFailed
This event triggers when a payment attempt fails, further attempts can be made
for the payment. An error message will appear in the payment UI, and the
payer will be able to try again or choose another payment instrument. The
onPaymentTransactionFailed
event is raised with the following event argument
object:
onPaymentTransactionFailed event object
1
2
3
4
{
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"details": "[HttpCode ProblemTitle]"
}
Field | Type | Description |
---|---|---|
id |
string |
The relative URI and unique identifier of the payment resource this payer belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
details |
string |
A human readable and descriptive text of the error. |
onExternalRedirect
This event triggers when a user is redirected to a separate web page, for
example 3-D Secure or Bank ID signing. The onExternalRedirect
event is raised
with the following event argument object:
onExternalRedirect event object
1
2
3
{
"redirectUrl": "https://external.example.com/"
}
Field | Type | Description |
---|---|---|
redirectUrl |
string |
The URI the user will be redirected to when a third party requires additional data. |
onError
Triggered on terminal errors, and when the configuration fails validation.
Callback
While the callback feature is mandatory, we would like to emphasize that it is mainly a fail-safe feature. We strongly advice that it is not your primary mean of checking for payment updates.
When a change or update from the back-end system are made on a payment or transaction, Swedbank Pay will perform a callback to inform the payee (merchant) about this update.
Providing a callbackUrl
in POST
requests is mandatory. Below we provide
three example scenarios of why this is important:
- If the payer closes the payment window, the merchant will never know what
happened to the payment if
callbackUrl
is not implemented. - If the payer stops up in a payment app such as Vipps or Swish, the payer
will never come back to the merchant. This means that the merchant won’t
know what happened to the payment unless
callbackUrl
is implemented. - If a payer experiences a network error or something else happens that
prevents the payer from being redirected from Swedbank Pay back to the
merchant website, the
callbackUrl
is what ensures that you receive the information about what happened with the payment.
- When a change or update from the back-end system are made on a payment or transaction, Swedbank Pay will perform an asynchronous server-to-server callback to inform the payee (merchant) about this update.
- It is important to know that the callback is asynchronous, and not real-time. As we can’t guarantee when you get the callback, there could be a delay between when the payer is returned back to the merchant and when the callback arrives. If the merchant chooses to wait for the callback, the payer might be left at the merchant’s page until the response comes.
- Swedbank Pay will make an HTTP
POST
to thecallbackUrl
that was specified when the payee (merchant) created the payment. - When the
callbackUrl
receives such a callback, an HTTPGET
request must be made on the payment or on the transaction. The retrieved payment or transaction resource will give you the necessary information about the recent change/update. - As it isn’t scaled to be a primary source of updates, no given response time
can be guaranteed, and a callback might fail. It will be retried if that
should happen. Below are the retry timings, in seconds from the initial
transaction time:
- 30 seconds
- 60 seconds
- 360 seconds
- 432 seconds
- 864 seconds
- 1265 seconds
- A callback should return a
200 OK
response.
Differing IP addresses
Please note that the callback is sent from 91.132.170.1
in
the external integration environment and from 82.115.146.1
in
the production environment.
To understand the nature of the callback, the type of transaction, its status,
etc., you need to perform a GET
request on the received URI and inspect the
response. The transaction type or any other information can not and should not
be inferred from the URI. See URI usage for more information.
Payment Order Callback
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"paymentorder": {
"id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"instrument": "paymentorders"
},
"payment": {
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"number": 222222222
},
"transaction": {
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"number": 333333333
}
}
When performing an HTTP GET
request towards the URI found in the
transaction.id
field of the callback, the response is going to look
something like the abbreviated example provided below.
The created authorization
resource contains information about the
authorization
transaction made against a paymentorders
payment.
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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"authorization": {
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"itemDescriptions": {
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
},
"transaction": {
"id": "/psp/paymentorders/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": "Authorization",
"state": "Completed",
"number": 1234567890,
"amount": 1000,
"vatAmount": 250,
"description": "Test transaction",
"payeeReference": "AH123456",
"isOperational": false,
"problem": {
"type": "https://api.payex.com/psp/errordetail/paymentorders/3DSECUREERROR",
"title": "Error when complete authorization",
"status": 400,
"detail": "Unable to complete 3DSecure verification!",
"problems": [
]
"operations": [
{
"href": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"rel": "edit-authorization",
"method": "PATCH"
}
]
}
}
}
Field | Type | Description | |
---|---|---|---|
payment |
string |
The relative URI and unique identifier of the payment resource this authorization belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
authorization |
string |
The current authorization transaction resource. |
|
└➔ id
|
string |
The relative URI and unique identifier of the authorization resource this authorization belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
└➔ itemDescriptions
|
object |
The object representation of the itemDescriptions resource. |
|
└─➔ id
|
string |
The relative URI and unique identifier of the itemDescriptions resource this authorization belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
└➔ transaction
|
object |
The object representation of the generic transaction resource. | |
└─➔ id
|
string |
The relative URI and unique identifier of the transaction resource this authorization 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 authorization 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. |
|
└─➔ receiptReference
|
string |
A unique reference for the transaction. This reference is used as an invoice/receipt number. | |
└─➔ failedReason
|
string |
The human readable explanation of why the payment failed. | |
└─➔ 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. |
The sequence diagram below shows the HTTP POST
you will receive from Swedbank
Pay, and the two GET
requests that you make to get the updated status.
sequenceDiagram
Participant Merchant
Participant SwedbankPay as Swedbank Pay
activate SwedbankPay
SwedbankPay->>+Merchant: POST <callbackUrl>
deactivate SwedbankPay
note left of Merchant: Callback by Swedbank Pay
Merchant-->>+SwedbankPay: HTTP response
Merchant->>+SwedbankPay: GET paymentorders payment
deactivate Merchant
note left of Merchant: First API request
SwedbankPay-->>+Merchant: payment resource
deactivate SwedbankPay
Problems
When performing operations against a resource in the Swedbank Pay API Platform, it will respond with a problem message that contain details of the error type if the request could not be successfully performed. Regardless of why the error occurred, the problem message will follow the same structure as specified in the Problem Details for HTTP APIs (RFC 7807) specification.
We generally use the problem message type
and status
code to identify the
nature of the problem. The problems
array contains objects with name
and
description
that will often help narrow down the specifics of the problem,
usually to the field in the request that was missing or contained invalid data.
The structure of a problem message will look like this:
Problem Example
1
2
3
4
5
6
7
8
9
10
11
12
{
"type": "https://api.payex.com/psp/errordetail/<resource>/inputerror",
"title": "There was an input error",
"detail": "Please correct the errors and retry the request",
"instance": "ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"status": 400,
"action": "RetryNewData",
"problems": [{
"name": "CreditCardParameters.Issuer",
"description": "minimum one issuer must be enabled"
}]
}
Field | Type | Description |
---|---|---|
type |
string |
The URI that identifies the error type. This is the only field usable for programmatic identification of the type of error! When dereferenced, it might lead you to a human readable description of the error and how it can be recovered from. |
title |
string |
The title contains a human readable description of the error. |
detail |
string |
A detailed, human readable description of the error and how you can recover from it. |
instance |
string |
The identifier of the error instance. This might be of use to Swedbank Pay support personnel in order to find the exact error and the context it occurred in. |
status |
integer |
The HTTP status code that the problem was served with. |
action |
string |
The action indicates how the error can be recovered from. |
problems |
array |
The array of problem detail objects. |
└➔ name
|
string |
The name of the field, header, object, entity or likewise that was erroneous. |
└➔ description
|
string |
The human readable description of what was wrong with the field, header, object, entity or likewise identified by name . |
Common Problems
All common problem types will have a URI in the format
https://api.payex.com/psp/errordetail/<error-type>
. The URI is an
identifier that you can hard-code and implement logic around. It is currently
not not possible to dereference this URI, although that might be possible in the
future.
Type | Status | Description |
---|---|---|
inputerror |
400 |
The server cannot or will not process the request due to an apparent client error (e.g. malformed request syntax, size to large, invalid request). |
forbidden |
403 |
The request was valid, but the server is refusing the action. The necessary permissions to access the resource might be lacking. |
notfound |
404 |
The requested resource could not be found, but may be available in the future. Subsequent requests are permissible. |
systemerror |
500 |
A generic error message. |
configurationerror |
500 |
A error relating to configuration issues. |
Payment Instrument Specific Problems
Problem types for a specific payment instrument will have a URI in the format
https://api.payex.com/psp/errordetail/<payment-instrument>/<error-type>
. You
can read more about the payment instrument specific problem messages below:
Expansion
The payment resource contain the ID of related sub-resources in its response
properties. These sub-resources can be expanded inline by using the request
parameter expand
. This is an effective way to limit the number of necessary
calls to the API, as you return several properties related to a Payment resource
in a single request.
Note that the expand
parameter is available to all API requests but only
applies to the request response. This means that you can use the expand
parameter on a POST
or PATCH
request to get a response containing the target
resource including expanded properties.
This example below add the urls
and authorizations
field inlines to the
response, enabling you to access information from these sub-resources.
Expansion
1
2
GET /psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1?$expand=urls,authorizations HTTP/1.1
Host: api.externalintegration.payex.com
To avoid unnecessary overhead, you should only expand the nodes you need info about.
PayeeInfo
The payeeinfo
resource contains information about the payee (i.e. a merchant,
a corporation etc) related to a specific payment.
Request
1
2
3
4
GET /psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"payeeInfo": {
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo",
"payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
"payeeReference": "EN1234",
"payeeName": "TestMerchant1",
"productCategory": "EF1234",
"orderReference": "or-123456"
}
}
Field | Type | Description |
---|---|---|
payment |
string |
The relative URI and unique identifier of the payment resource this payeeInfo belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ id
|
string |
The relative URI and unique identifier of the payeeInfo resource this payeeInfo belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ payeeId
|
string |
This is the unique id that identifies this payee (like merchant) set by Swedbank Pay |
└➔ 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. |
└➔ payeeName
|
string |
The payee name (like merchant name) that will be displayed when redirected to Swedbank Pay. |
└➔ productCategory
|
string |
A product category or number sent in from the payee/merchant. This is not validated by Swedbank Pay, but will be passed through the payment process and may be used in the settlement process. You therefore need to ensure that the value given here is valid in the settlement. |
└➔ orderReference
|
string(50) |
The order reference should reflect the order reference found in the merchant’s systems. |
Payee Reference
The payeeReference
given when creating transactions and payments has some
specific processing rules depending on specifications in the contract.
- It must be unique for every operation, used to ensure exactly-once delivery of a transactional operation from the merchant system.
- Its length and content validation is dependent on whether the
transaction.number
or thepayeeReference
is sent to the acquirer.- If you select Option A in the settlement process (Swedbank Pay will
handle the settlement), Swedbank Pay will send the
transaction.number
to the acquirer and thepayeeReference
must be in the format of charactersA-Za-z0-9
(including-
) andstring(30)
. - If you select Option B in the settlement process (you will handle the
settlement yourself), Swedbank Pay will send the
payeeReference
to the acquirer and it will be limited to the format ofstring(12)
and all characters must be digits.
- If you select Option A in the settlement process (Swedbank Pay will
handle the settlement), Swedbank Pay will send the
Metadata
Metadata can be used to store data associated to a payment order
that can be retrieved later by performing a GET
on the
payment order.
Swedbank Pay does not use or process metadata
, it is only stored on the
payment order so it can be retrieved later alongside the
payment order. An example where metadata
might be useful is when
several internal systems are involved in the payment process and the payment
creation is done in one system and post-purchases take place in another.
In order to transmit data between these two internal systems, the data can be
stored in metadata
on the payment order so the internal systems do
not need to communicate with each other directly.
The usage of metadata
field is shown in the abbreviated Purchase
request
below.
Request
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
POST /psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/ HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"payment": {
"operation": "Purchase",
"intent": "Authorization",
"currency": "SEK",
"description": "Test Purchase",
"userAgent": "Mozilla/5.0...",
"language": "sv-SE",
"urls": {
"hostUrls": ["https://example.com"],
"completeUrl": "https://example.com/payment-completed"
},
"payeeInfo": {
"payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
"payeeReference": "CD1234",
},
"payer": {
"payerReference": "AB1234",
},
"metadata": {
"key1": "value1",
"key2": 2,
"key3": 3.1,
"key4": false
},
"prefillInfo": {
"msisdn": "+4798765432"
}
}
}
Parameter | Type |
---|---|
metadata |
string , boolean , integer ,decimal
|
Request
1
2
3
4
GET /psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/ HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"metadata": {
"id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/metadata",
"key1": "value1",
"key2": 2,
"key3": 3.1,
"key4": false
}
}
Settlement and Reconciliation
Reconciliation is an important step in an economic transaction. When a payment is reconciled, captured amounts for the payment are matched against the corresponding settlement.
The information needed to reconcile captured funds - the balance report and transactions list - are available for all merchants using Swedbank Pay.
- By default, the settlement files will be sent to you by via e-mail.
- We also have the option to send it via SFTP as well, if this is something you would like then you need to state this to your sales representative, so they can inform the setup team when the time is ready.
- The settlement frequency is defined in the agreement and you will receive it (per default) once a month, or once a week.
- You do not need to subscribe, the files will be delivered by default.
Contact omni.client@swedbankpay.se for further inquiries regarding this.
Settlement
There are two main alternatives for settlement - either we handle the settlement process for you, or you handle the process yourself :
Swedbank Pay handles the settlement process
Swedbank Pay handles the settlement process on your behalf, (called “Redovisningsservice”). Swedbank Pay transfers the net amount to you directly.
Swedbank Pay Checkout
When choosing Swedbank Pay Checkout we always handle the settlement process for you, gathering all your eCommerce payments in one place. Straighforward and time efficient.
You handle the settlement process yourself
If you will handle the settlement yourself, then Swedbank Pay will send you an invoice with the relevant fees, in addition to the report and transactions lists. Your acquirer will transfer settled funds to you.
Balance Report
The Balance Report (a .pdf file) specifies the total sales for a specific period, including fees and VAT. The report contains three parts: a payment summary and specifications for sales and for fees.
Payment Summary
Provides a summary of the Amount
sold, Fees
and VAT
. If Swedbank Pay
handles the settlement process, the Transfered
amount
- shown in the
balance report summary is equivalent to the disbursement on the bank statement
(the remaining total amount after fees).
Sales specification
Provides a specification over sales for the given period. The sales total is
specified per payment area (CreditCard
, Invoice
) and
underlying payment instruments. Each sales row specify Quantity, Sum sales and
Amount to pay out, the last one is only eligble if Swedbank Pay handles the
Settlement process.
Fees specification
Provides a specification over fees for the given period. The fees total is
specified per payment area (CreditCard
, Invoice
) and
underlying payment instruments. Each fees row specify Quantity
(sales),
Amount
(sales), Unit price
, Provision
and fee Amount
. If you handle
the settlement process yourselves you will receive a separat invoice for fees.
Transactions List
The Transaction List (provided in .xlsx
and .xml
formats) specifies all
transactions for a specific period, including a summary of transactions grouped
by payment instrument. Both formats contain the same information, but the xml
file is meant for computer processing while the excel workbook is meant for
human interaction.
The first row contains the name of the Swedbank Pay company (e.g. Swedbank Pay Solutions AB) that the merchant has the contract with, and the balance report number. The header fields contain a summary of the transactions displayed in the body.
Header fields
Field | Type | Description |
---|---|---|
Prefix |
String |
The Prefix used for transactions, only eligible if merchant uses prefix. |
Currency | ISO 4217 |
Settlement currency (e.g. SEK, NOK, EUR ). |
ServiceType |
String |
The service type of the service used (e.g. Creditcard ). |
Service |
String |
The service used (e.g. Creditcard ). |
NoOfDebet |
Decimal |
Total number of debit transactions for the given service. |
NoOfCredit |
Decimal |
Total number of credit transactions for the given service. |
Amount |
Decimal |
Total amount for the given service (e.g 100.00). |
FromDate |
ISO 8601 |
The earlistest transaction date, YYYY-MM-DD . |
ToDate |
ISO 8601 |
The latest transaction date, YYYY-MM-DD . |
Body fields
Field | Type | Description |
---|---|---|
Swedbank Pay Batch Number |
Decimal |
A batch number common to all types of transactions processed by Swedbank Pay. |
Transaction Number |
Decimal |
A unique identifier of the transaction, can be traced in Swedbank Pay Admin user interface. |
Order id |
String |
A unique identifier of the order, as sent from the merchant to Swedbank Pay. Transactions that are related to the same order are associated with this ID. |
Date Created |
ISO 8601 |
Transaction capture date/time. YYYY-MM-DD hh:mm:ss. |
Date Modified |
ISO 8601 |
Transaction settle date/time. YYYY-MM-DD hh:mm:ss. |
Provider |
String |
The service provider (e.g. Babs, Swedbank). |
Type |
String |
The service type of the related transaction (e.g. Creditcard ). |
Amount |
Decimal |
Total amount of the related transaction (e.g 100.00). |
Currency |
ISO 4217 |
Settlement currency (e.g. SEK, NOK, EUR ). |
Product Number |
String |
A product number, as sent by merchant to Swedbank Pay. |
Description |
String |
A textual description of the transaction, as sent by merchant to Swedbank Pay. |
VAT Amount |
Decimal |
VAT Amount for the given transaction (e.g 100.00). |
VAT Percentage |
Decimal |
VAT Percentage for the given transaction. |
Credit Card Batch Number |
Decimal |
The reference number from the credit card processor. |
Reference |
Decimal |
The transaction reference from processor. |
Swedbank Pay Account Number |
Decimal |
The Account number given, shown in Swedbank Pay admin. |
Referenced Transaction Number |
Decimal |
Transaction number for the Authoriation transaction for a two-stage transaction or the number of the debit transaction if it is a credit transaction. |
Sales Channel |
String |
The channel through which the transaction was sent to Swedbank Pay (e.g Transaction via eCommerce APIs). |
Brand |
String |
If eligible, Branding information as sent by merchant to Swedbank Pay. |
Point Of Sale |
String |
If eligible, POS information as sent by merchant to Swedbank Pay. |
Reconciliation
To do the reconciliation, you need to match the information in your system against the information provided by Swedbank Pay in the balance report and transaction list. Below is a sequence diagram detailing the interaction.
sequenceDiagram
participant SwedbankPay as Swedbank Pay
activate Merchant
activate SwedbankPay
Merchant-->>SwedbankPay: Online payment transactions
deactivate Merchant
deactivate SwedbankPay
activate Merchant
SwedbankPay->>Merchant: Balance Report (PDF-file)
note left of Merchant: files are sent by e-mail or file transfer
SwedbankPay->>Merchant: Transaction list (XLSX-file)
SwedbankPay->>Merchant: Transaction list (XML-file)
deactivate Merchant
There are two ways for you to match the information from your system with the information given in the reconciliation files from Swedbank Pay:
- You can use information generated by your system (you will have to set a unique payeeReference when you make the transaction), or
- You can use the transaction number generated by Swedbank Pay (this is called transaction number and is returned from Swedbank Pay after you have created the transaction).
A credit card transaction is made when you either make a capture or a reversal.
In the input data for making a capture, you will set the payeeReference
. The
unique value of this field is the same as the field called OrderID
in the
reconciliation file.
1
2
3
4
5
6
7
8
{
"transaction": {
"amount": 1500,
"vatAmount": 0,
"description": "Test Reversal",
"payeeReference": "ABC123"
}
}
When you receive the response from Swedbank Pay, the response will include
transaction.number
. This is the same as the field called TransactionNo
in
the reconciliation file.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
"payment": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"capture": {
"id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"transaction": {
"id": "/psp/paymentorders/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": "Initialized",
"number": 1234567890,
"amount": 1500,
"vatAmount": 250,
"description": "Test Capture",
"payeeReference": "ABC123",
"failedReason": "",
"isOperational": false,
"operations": []
}
}
}
-
payeeReference
sent to Swedbank Pay is equal toOrderId
in the reconciliation file. -
capture.transaction.number
returned from Swedbank Pay is equal toTransactionNo
in reconciliation file.
Below you will see the API mapping tables to the fields in the settlement
report for Capture
and Reversal
.
Capture
API | XLSX | XML | |
---|---|---|---|
Swedbank Pay Batch Number |
SwedbankbatchNo |
||
transaction.number |
Transaction Number |
TransactionNo |
|
transaction.payeeReference |
Order id |
OrderId |
|
transaction.created |
Date Created |
DateCreated |
|
Date Modified |
DateModified |
||
Provider |
Provider |
||
Type |
Type |
||
transaction.amount |
Amount |
Amount |
|
Currency |
Currency |
||
Product Number |
MerchantProductNo |
||
transaction.description |
Description |
Description |
|
transaction.vatAmount |
VAT Amount |
VATAmount |
|
VAT Percentage |
VatoPercentage |
||
Credit Card Batch Number |
CreditCardBatchNo |
||
transaction.number if DirectDebit |
Direct Debit Bank Reference |
DirectDebitbankRef |
|
transaction.number if DirectDebit |
Reference |
Reference |
|
Swedbank Account Number |
SwedbankAccountNo |
||
transaction.number if reversed later |
Referenced Transaction Number |
ReferencedTransaction |
|
Sales Channel |
SalesChannel |
||
Brand |
|||
Point Of Sale |
Reversal
API | XLSX | XML | |
---|---|---|---|
Swedbank Pay Batch Number |
SwedbankbatchNo |
||
transaction.number |
Transaction Number |
TransactionNo |
|
transaction.payeeReference |
Order id |
OrderId |
|
transaction.created |
Date Created |
DateCreated |
|
Date Modified |
DateModified |
||
Provider |
Provider |
||
Type |
Type |
||
transaction.amount |
Amount |
Amount |
|
Currency |
Currency |
||
Product Number |
MerchantProductNo |
||
transaction.description |
Description |
Description |
|
transaction.vatAmount |
VAT Amount |
VATAmount |
|
VAT Percentage |
VatoPercentage |
||
Credit Card Batch Number |
CreditCardBatchNo |
||
transaction.number if DirectDebit |
Direct Debit Bank Reference |
DirectDebitbankRef |
|
transaction.number if DirectDebit |
Reference |
Reference |
|
Swedbank Account Number |
SwedbankAccountNo |
||
Referenced Transaction Number |
ReferencedTransaction |
||
Sales Channel |
SalesChannel |
||
Brand |
|||
Point Of Sale |
Samples
The content of the files depends on the type of agreement you have made with Swedbank Pay. For some payment instruments, only option A is available, while for other payment instruments, only option B is available. The sample files can be downloaded below.
Option A: Swedbank Pay handles the settlement process
- PDF Balance Report for Swedbank Pay Checkout
- PDF Balance Report
- XLSX Transaction List
- XML Transaction List
Option B: You will handle the settlement process yourself
Split Settlement
The split settlement feature is the easy way of doing settlements for companies with multiple sub merchants. With a few easy steps, the settlement process becomes more efficient with regards to invoicing, payouts and setup for both your sub merchants and yourself.
In short, it is a settlement feature where a company with a website or an app can attach specific subsite numbers to sub merchants selling their goods or services through the company. The subsite number is used to match the transactions with the correct sub merchant, so the settlement is automatically split between them. If you run a site selling tickets to concerts, theatres, sporting events etc., each venue gets its own subsite number. If you run a funeral home, the sub merchants can be everything from flower shops to charities.
What we need from you as a company
- Submit a KYC (Know Your Costumer) form for each sub merchant you want to include. We will also do a KYC check on your sub merchants, providing extra security for you.
- Give every sub merchant who sells goods/services through your website or in your app a unique subsite number. This must be included in the KYC form. We recommend using the same customer number they have in your system.
- Attach the subsite number to all the goods/services the sub merchant sells through your website or app, so the goods/services can be matched to the correct merchant in our back office system.
- A partner agreement is needed for automatic deduction of revenue cuts and fees.
How it works
- We set up the sub merchant subsite number in our systems.
- That number is added in the requests subsite field in when you create the payment for the goods or service.
- The customer selects payment instrument and completes the payment.
- The payment goes into the client funds account.
- Swedbank Pay matches the transaction and the merchant using the subsite number.
- The settlement is split and connected to the correct merchant.
- Revenue cuts for the super merchant and fees from Swedbank Pay are deducted automatically.
- Payout to the sub merchant is done.
The upsides
Sub merchants being connected to Swedbank Pay through the super merchant instead of having separate setups has a lot of pros:
- You only need one agreement for each payment instrument (credit card, Vipps, Swish, MobilePay Online, invoice) and payment gateway.
- You only need one acquiring agreement.
- You only one Vipps or Swish certificate.
- You can add more payment instruments easily, as it only has to be done once.
- New sub merchants can be set up quickly, as the only thing needed is a KYC form and a subsite number. This shortens the setup time for both you and us to a matter of hours.
- The automatic settlement split and deduction of fees and revenue cuts minimizes the work for your accounting department, as you do not have to invoice your sub merchants.
- The subsite split is available for all the payment instruments we offer on our eCom platform.
Good to know
With regards to admin functions, we offer a full integration towards our admin system. This way, you do not have to log in to Swedbank Pay Admin to perform these operations.
Captures and cancels
Captures and cancels are done by the super merchant the same way as any other normal flow.
Reversals
In cases where you need to do reversals, this will be performed by the super merchant. The reversal amount will be charged from the sub merchants subsite number. If the sub merchants balance is 0 (zero), the super merchant will be invoiced. The super merchant will in turn have to invoice this amount to the sub merchant.
Transaction on file
This feature is only available for merchants who have a specific agreement with Swedbank Pay.
In rare use cases it can be useful for Merchants that operate with payment tokens (recurring, one-click, etc) to be able to submit subsequent transactions via file transfer rather than using the regular operations in our API. Reasons for this could be that the subsequent transactions are triggered from an older system that do not support real-time API communication. For those use cases Swedbank Pay offer a service called Transaction on File. As this is a somewhat unmodern way to complete transactions, we strongly recommend to consider usage of regular API operations and only use transactions on file where it is the only option.
For further information on this service, please contact our integration support.
Screenshots
You will redirect the payer to Swedbank Pay hosted pages to collect the credit card information.
API Requests
The API requests are displayed in the flow below. The token generated will be returned in parameter ‘transactionOnFileToken’. For more information regarding the flow, see Verify.
Request
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
POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"payment": {
"operation": "Verify",
"currency": "NOK",
"description": "Create TransactionOnFileToken",
"userAgent": "Mozilla/5.0...",
"language": "nb-NO",
"generateTransactionOnFileToken": true,
"urls": {
"hostUrls": ["https://example.com", "https://example.net"],
"completeUrl": "https://example.com/payment-completed",
"cancelUrl": "https://example.com/payment-canceled",
"logoUrl": "https://example.com/payment-logo.png",
"termsOfServiceUrl": "https://example.com/payment-terms.html"
},
"payeeInfo": {
"payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
"payeeReference": "CD1234",
"payeeName": "Merchant1",
"productCategory": "A123",
"orderReference": "or-12456",
"subsite": "MySubsite"
},
"payer": {
"payerReference": "AB1234",
}
}
}
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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment": {
"id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"number": 1234567890,
"created": "2016-09-14T13:21:29.3182115Z",
"updated": "2016-09-14T13:21:57.6627579Z",
"operation": "Verify",
"state": "Ready",
"currency": "NOK",
"amount": 0,
"description": "Test Verification",
"initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
"userAgent": "Mozilla/5.0",
"language": "nb-NO",
"transactions": { "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions" },
"verifications": { "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/verifications" },
"urls" : { "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls" },
"payeeInfo" : { "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo" },
"payers": { "id": ""/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers" },
"settings": { "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/settings" }
},
"operations": [
{
"href": "https://api.externalintegration.payex.com/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"rel": "update-payment-abort",
"method": "PATCH",
"contentType": "application/json"
},
{
"href": "https://ecom.externalintegration.payex.com/paymentorders/verification/5a17c24e-d459-4567-bbad-aa0f17a76119",
"rel": "redirect-verification",
"method": "GET",
"contentType": "application/json"
},
{
"method": "GET",
"href": "https://ecom.externalintegration.payex.com/paymentorders/core/scripts/client/px.creditcard.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119",
"rel": "view-verification",
"contentType": "application/javascript"
}
]
}
3-D Secure 2
When dealing with card payments, 3-D Secure authentication of the cardholder is an essential topic. 3-D Secure 2 is an improved version of the old protocol, now allowing frictionless payments where transactions can be completed without input from the cardholder. Therefore, there are certain fields that should be included when implementing 3-D Secure 2. These are listed below and can be seen in the abbreviated request example below.
Request
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
POST /psp/paymentorders/payments HTTP/1.1
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"paymentorder": {
"operation": "Purchase",
"intent": "Authorization",
"currency": "SEK",
"description": "Test Purchase",
"urls": {
"hostUrls": ["https://example.com"]
},
"payer": {
"email": "olivia.nyhuus@payex.com",
"msisdn": "+4798765432",
"workPhoneNumber" : "+4787654321",
"homePhoneNumber" : "+4776543210",
"shippingAddress": {
"addressee": "Olivia Nyhuus",
"streetAddress": "Saltnestoppen 43",
"coAddress": "",
"city": "Saltnes",
"zipCode": "1642",
"countryCode": "NO"
}
},
"riskIndicator": {
"deliveryEmailAddress": "olivia.nyhuus@payex.com",
"deliveryTimeFrameIndicator": "01",
"preOrderDate": "19801231",
"preOrderPurchaseIndicator": "01",
"shipIndicator": "01",
"giftCardPurchase": false,
"reOrderPurchaseIndicator": "01"
"pickUpAddress" : {
"name" : "Company Megashop Sarpsborg",
"streetAddress" : "Hundskinnveien 92",
"coAddress" : "",
"city" : "Sarpsborg",
"zipCode" : "1711",
"countryCode" : "NO"
}
}
}
}
Field | Type | Description |
---|---|---|
└➔ paymentorder
|
object |
The relative URI and unique identifier of the paymentorder resource this payer belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ payer
|
object |
The payer object. |
└➔ email
|
string |
Payer’s registered email address. The field is related to 3-D Secure 2. |
└➔ msisdn
|
string |
Payer’s registered mobile phone number. The field is related to 3-D Secure 2. |
└➔ homePhoneNumber
|
string |
Payer’s registered home phone number. The field is related to 3-D Secure 2. |
└➔ workPhoneNumber
|
string |
Payer’s registered work phone number. The field is related to 3-D Secure 2. |
└➔ shippingAddress
|
object |
The shipping address object related to the payer . The field is related to 3-D Secure 2. |
└─➔ addresse
|
string |
The name of the addressee – the receiver of the shipped goods. |
└─➔ coAddress
|
string |
Payer’ s c/o address, if applicable. |
└─➔ streetAddress
|
string |
Payer’s street address. Maximum 50 characters long. |
└─➔ zipCode
|
string |
Payer’s zip code |
└─➔ city
|
string |
Payer’s city of residence |
└─➔ countryCode
|
string |
Country Code for country of residence. |
└➔ riskIndicator
|
object |
This object consist of information that helps verifying the payer. Providing these fields decreases the likelihood of having to promt for 3-D Secure authentication of the payer when they are authenticating the purchase. |
└─➔ deliveryEmailAdress
|
string |
For electronic delivery, the email address to which the merchandise was delivered. Providing this field when appropriate decreases the likelyhood of a 3-D Secure authentication for the payer. |
└─➔ deliveryTimeFrameIndicator
|
string |
ndicates the merchandise delivery timeframe. 01 (Electronic Delivery) 02 (Same day shipping) 03 (Overnight shipping) 04 (Two-day or more shipping). |
└─➔ preOrderDate
|
string |
For a pre-ordered purchase. The expected date that the merchandise will be available. Format: YYYYMMDD . |
└─➔ preOrderPurchaseIndicator
|
string |
Indicates whether the payer is placing an order for merchandise with a future availability or release date. 01 (Merchandise available) 02 (Future availability). |
└─➔ shipIndicator
|
string |
Indicates shipping method chosen for the transaction. 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 the riskIndicator.pickUpAddress and payer.shippingAddress 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 |
Indicates whether the cardholder is reordering previously purchased merchandise. 01 (First time ordered) 02 (Reordered). |
Updating Payment Menu
When the contents of the shopping cart changes or anything else that affects
the amount occurs, the paymentorder
must be updated and the Payment Menu
must be refresh
ed.
Features that are
not described in the previous sections must not be used, although they are
available in the API. Flags that can be turned to true
must be kept false
as
described in this standard setup documentation.