Swedbank Pay Checkout – Other Features

After a successful integration, it may be worth investigating which other features are available in Swedbank Pay Checkout. They are listed on this very page.

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 Swedbank Pay Checkout. 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 amount (including VAT, if any) to charge the payer, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.
└➔ vatAmount integer The amount of VAT to charge the payer, entered in the lowest monetary unit ofthe selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. If the amount given includes VAT, vatAmount may be displayed for the user inthe payment page (redirect only). 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 consumer’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 URI to the payeeinfo resource where the information about the payee of the payment order can be retrieved.
└➔ 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 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
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",
        "generateRecurrenceToken": 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": {  
            "consumerProfileRef": "5a17c24e-d459-4567-bbad-aa0f17a76119",
            "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,
            }
        ],
        "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
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",
        "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 amount (including VAT, if any) to charge the payer, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.  
check └➔ vatAmount integer The amount of VAT to charge the payer, entered in the lowest monetary unit ofthe selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. If the amount given includes VAT, vatAmount may be displayed for the user inthe payment page (redirect only). Set to 0 (zero) if there is no VAT amount charged.  
check └➔ description string The description of the payment order.  
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 └➔ 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.  
  └─➔ 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.  
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.  
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 object The payer object containing information about the payer relevant for the payment order.  
︎︎︎ └─➔ consumerProfileRef string The consumer profile reference as obtained through initiating a consumer session.  
  └─➔ 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]* (a-zA-Z0-9_). 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 a free-text field and 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 amount (including VAT, if any) to charge the payer, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.  
check └─➔ vatAmount integer The amount of VAT to charge the payer, entered in the lowest monetary unit ofthe selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. If the amount given includes VAT, vatAmount may be displayed for the user inthe payment page (redirect only). Set to 0 (zero) if there is no VAT amount charged.  
  └➔ riskIndicator array This optional 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 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.  
  └─➔ 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.  
└➔ 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 amount (including VAT, if any) to charge the payer, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.  
└➔ vatAmount integer The amount of VAT to charge the payer, entered in the lowest monetary unit ofthe selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. If the amount given includes VAT, vatAmount may be displayed for the user inthe payment page (redirect only). 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 consumer’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 URI to the payeeinfo resource where the information about the payee of the payment order can be retrieved.  
└➔ 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 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.  

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 - Reference1583419461 in the the code example.

info

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 - Reference1583419461",
        "generateRecurrenceToken": false,
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "urls":
            "hostUrls": ["https://example.com"]
        }
}

The description field as presented in the Payment Menu

URLs

When creating a Payment Order, the urls field of the paymentOrder contains the related URIs, including where the consumer gets 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.
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.
  callbackUrl string The URI to the API endpoint receiving POST requests on transaction activity related to the payment order.
  logoUrl string The URI to the logo that will be displayed on redirect pages. HTTPS is a requirement.

Payment Url

Payment Url

For our Seamless Views, the field called paymentUrl will be used when the consumer is redirected out of the Seamless View (the iframe). The consumer 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.

info

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 consumer 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 consumer 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 consumer 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/payments/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.
└➔ 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.
└➔ 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 The URI that will be used for showing the customer logo. Must be a picture with at most 50px height and 400px width.
└➔ 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]* (a-zA-Z0-9_). 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 amount (including VAT, if any) to charge the payer, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.
check vatAmount integer The amount of VAT to charge the payer, entered in the lowest monetary unit ofthe selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. If the amount given includes VAT, vatAmount may be displayed for the user inthe payment page (redirect only). 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 consumer 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.

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.

info

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 consumer 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!

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.

info

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 amount (including VAT, if any) to charge the payer, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.
check └➔ vatAmount integer The amount of VAT to charge the payer, entered in the lowest monetary unit ofthe selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. If the amount given includes VAT, vatAmount may be displayed for the user inthe payment page (redirect only). 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]* (a-zA-Z0-9_). 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 a free-text field and 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 5000 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 5000 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/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.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 amount (including VAT, if any) to charge the payer, 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.
└➔ payerReference string The reference to the payer (consumer/end-user) from the merchant system, like e-mail address, mobile number, customer number etc.
└➔ userAgent string The user agent string of the consumer’s browser.
└➔ language string sv-SE, nb-NO, da-DK, de-DE, ee-EE, en-US, es-ES, fr-FR, lv-LV,lt-LT, ru-RU or fi-FI.
└➔ urls string The URI to the urls resource where all URIs related to the payment can be retrieved.
└➔ payeeInfo string The URI to the payeeinfo resource where the information about the payee of the payment 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 amount (including VAT, if any) to charge the payer, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.
└─➔ vatAmount integer The amount of VAT to charge the payer, entered in the lowest monetary unit ofthe selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. If the amount given includes VAT, vatAmount may be displayed for the user inthe payment page (redirect only). 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 amount (including VAT, if any) to charge the payer, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.
check └➔ vatAmount integer The amount of VAT to charge the payer, entered in the lowest monetary unit ofthe selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. If the amount given includes VAT, vatAmount may be displayed for the user inthe payment page (redirect only). 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]* (a-zA-Z0-9_). 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 a free-text field and 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",
    "reversals": {
        "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 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 amount (including VAT, if any) to charge the payer, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.
└─➔ vatAmount integer The amount of VAT to charge the payer, entered in the lowest monetary unit ofthe selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. If the amount given includes VAT, vatAmount may be displayed for the user inthe payment page (redirect only). 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 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 amount (including VAT, if any) to charge the payer, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.  
└─➔ vatAmount integer The amount of VAT to charge the payer, entered in the lowest monetary unit ofthe selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. If the amount given includes VAT, vatAmount may be displayed for the user inthe payment page (redirect only). 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 consumer tries using another credit card) up to a maximum amount of retries (in that case which the payment order gets the state failed 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 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 amount (including VAT, if any) to charge the payer, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.  
└─➔ vatAmount integer The amount of VAT to charge the payer, entered in the lowest monetary unit ofthe selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. If the amount given includes VAT, vatAmount may be displayed for the user inthe payment page (redirect only). 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 field generateRecurrenceToken is set to true. 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

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
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
      }
    ]
  }
}
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 amount (including VAT, if any) to charge the payer, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.
check └➔ vatAmount integer The amount of VAT to charge the payer, entered in the lowest monetary unit ofthe selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. If the amount given includes VAT, vatAmount may be displayed for the user inthe payment page (redirect only). 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 consumer’s web browser.
check └─➔ language string sv-SE, nb-NO or en-US.
check └─➔ urls string {he 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).
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 to consumer 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]* (a-zA-Z0-9_). 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 a free-text field and 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.

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
PATCH /psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1 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
9
10
HTTP/1.1 200 OK
Content-Type: application/json
{
  "instrumentData": {
    "id": "/psp/paymentorders/instrumentdata/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "paymentToken": "5a17c24e-d459-4567-bbad-aa0f17a76119",
    "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
    "isDeleted": true 
  }
}

Purchase Flow

sequenceDiagram
    participant Payer
    participant ConsumerSubscription
    participant Merchant
    participant SwedbankPay as Swedbank Pay

    rect rgba(81,43,43,0.1)
        note left of Payer: Checkin
        activate Payer
        Payer ->>+ SwedbankPay: Checkin procedure
        deactivate Payer
    end
    rect rgba(55, 91, 134,0.1)
        activate Payer
        note left of Payer: Payment Menu
        Payer ->>+ Merchant: Initiate Purchase
        deactivate Payer
        Merchant ->>+ SwedbankPay: POST/psp/paymentorders (generateRecurrenceToken = True)
        deactivate Merchant
        SwedbankPay -->>+ Merchant: rel:view-paymentorder
        deactivate SwedbankPay
        Merchant -->>- Payer: Display Payment Menu on Merchant Page
        activate Payer
        Payer ->> Payer: Initiate Payment Menu Hosted View (open iframe)
        Payer -->>+ SwedbankPay: Show Payment UI page in iframe
        deactivate Payer
        SwedbankPay ->>+ Payer: 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
POST /psp/paymentorders/payments HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "payment": {
        "operation": "Verify",
        "currency": "NOK",
        "description": "Test Verification",
        "payerReference": "AB1234",
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "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"
        }
    },
    "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 amount (including VAT, if any) to charge the payer, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.  
check └➔ vatAmount integer The amount of VAT to charge the payer, entered in the lowest monetary unit ofthe selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. If the amount given includes VAT, vatAmount may be displayed for the user inthe payment page (redirect only). Set to 0 (zero) if there is no VAT amount charged.  
check └➔ description string The description of the payment order.  
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.  
  └─➔ 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.  
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.  
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.  

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
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": {
        "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",
        "operation": "Verify",
        "state": "Ready",
        "currency": "NOK",
        "amount": 0,
        "description": "Test Verification",
        "payerReference": "AB1234",
        "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" },
        "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.  
└➔ 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.  
└➔ payerReference string The reference to the payer (consumer/end-user) from the merchant system, like mobile number, customer number etc.  
└➔ initiatingSystemUserAgent string The system user agent used  
└➔ userAgent string The user agent string of the consumer’s browser.  
└➔ language string da-DK, fi-FI or en-US.  
└➔ urls string The URI to the urls resource where all URIs related to the payment can be retrieved.  
└➔ payeeInfo string The URI to the payeeinfo resource where the information about the payee of the payment 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 harbour one successful payment. This is necessary as the consumer might select and initiate a payment option that is not followed through successfully. I.e. if the consumer 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 consumer successfully should finish the purchase with a credit 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
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,
        "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",
        "payerReference": "AB1234",
        "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" },
        "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.
└➔ 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 amount (including VAT, if any) to charge the payer, 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.
└➔ payerReference string The reference to the consumer from the merchant system, like mobile number, customer number etc. Used in Merchant Identified Payer.
└➔ userAgent string The user agent string of the consumer’s browser.
└➔ language string sv-SE, nb-NO or en-US.

Prices

The prices resource lists the prices related to a specific payment.

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 amount (including VAT, if any) to charge the payer, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.
└─➔ vatAmount integer The amount of VAT to charge the payer, entered in the lowest monetary unit ofthe selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. If the amount given includes VAT, vatAmount may be displayed for the user inthe payment page (redirect only). Set to 0 (zero) if there is no VAT amount charged.

Prices Object Types

Each payment instrument have one or more prices object types. This is most relevant when using card based payments as each type correspond to a card brand or bank respectively.

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
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,
        "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.

The information is retrieved via a consumer profile token (consumerProfileRef), from the Consumers resource during login/checkin.

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
└─➔ zipCode string Payer’s zip code
└─➔ city string Payer’s city of residence
└─➔ countryCode string Country Code for country of residence.

Checkin Events

The Checkin Seamless View can inform about events that occur during Checkin through JavaScript event callbacks which can be implemented in the configuration object passed to the payex.hostedView.consumer(configuration) object.

sequenceDiagram
  participant Consumer
  participant Merchant
  participant SwedbankPay as Swedbank Pay
  Consumer ->> Merchant: visit
  Merchant ->> Merchant: Prepare, Embed ClientScript
  Merchant ->> SwedbankPay: payex.hostedView.consumer().open()
  alt Configuration validation failure
    SwedbankPay -->> Merchant: onError
  end
  alt Identified consumer
      SwedbankPay->>Merchant: onConsumerIdentified
      alt Depending on backend response
        SwedbankPay->>Merchant: onShippingDetailsAvailable
        SwedbankPay->>Merchant: onBillingDetailsAvailable
      end
  end
  alt Change shipping address
    Consumer->>SwedbankPay: Click change shipping adress button
    SwedbankPay->>Merchant: OnShippingDetailsAvailable
  end

onConsumerIdentified

This event triggers when a consumer has performed Checkin and is identified, if the Payment Menu is not loaded and in the DOM. The onConsumerIdentified event is raised with the following event argument object:

onConsumerIdentified event object

1
2
3
4
{
  "actionType": "OnConsumerIdentified",
  "consumerProfileRef": "5a17c24e-d459-4567-bbad-aa0f17a76119"
}

onShippingDetailsAvailable

Triggered when a consumer has been identified or shipping address has been updated.

info

The Checkin must be completed before any shipping details are finalized, as the Checkin component provides shipping address via the onShippingDetailsAvailable event.

onShippingDetailsAvailable event object

1
2
3
4
{
  "actionType": "OnBillingDetailsAvailable",
  "url": "/psp/consumers/5a17c24e-d459-4567-bbad-aa0f17a76119/shipping-details"
}

onBillingDetailsAvailable

Triggered when a consumer has been identified

onBillingDetailsAvailable event object

1
2
3
4
{
  "actionType": "OnBillingDetailsAvailable",
  "url":"/psp/consumers/5a17c24e-d459-4567-bbad-aa0f17a76119/billing-details"
}

Payment Menu Events

During operation in the Payment Menu, several events can occur. They are described below.

onPaymentPending

This events triggers when a payment enters a paying state ( Sale, Authorize, Canceletc). 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.

onPaymentTermsOfService

This event triggers when the user clicks on the “Display terms and conditions” link. The onPaymentTermsOfService event is raised with the following event argument object:

onPaymentTermsOfService 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 consumer 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

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:

  1. If the payer closes the payment window, the merchant will never know what happened to the payment if callbackUrl is not implemented.
  2. 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.
  3. 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.
  • Swedbank Pay will make an HTTP POST to the callbackUrl that was specified when the payee (merchant) created the payment.
  • When the callbackUrl receives such a callback, an HTTP GET 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.
  • The callback will be retried if it fails. Below are the retry timings, in seconds from the initial transaction time:
    • 30 seconds
    • 60 seconds
    • 360 seconds
    • 432 seconds
    • 864 seconds
    • 1265 seconds
  • The callback is sent from the following IP address: 82.115.146.1
  • A callback should return a 200 OK response.

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/<transaction type>/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "number": 333333333
    }
}
Parameter Description
<transaction type> authorizations, captures, cancellations,reversals
<payment instrument> creditcard, invoice, swish, vipps,mobilepay, callback

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.

info

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 PATCHrequest 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 to consumer 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 the payeeReference is sent to the acquirer.
    1. 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 the payeeReference must be in the format of characters A-Za-z0-9 (including -) and string(30).
    2. 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 of string(12) and all characters must be digits.

Merchant Authenticated Consumer

When the consumer is identified and authenticated by the merchant, the consumer’s identity can be included in the Payment Order request.

Merchant Authenticated Consumer is performed as an alternative to Checkin when creating the Payment Order upon the initializaiont of the Payment Menu. You can use Merchant Authenticated Consumer only if you have an agreement with Swedbank Pay. The additional nationalIdentifier field described below should be added to the paymentorder.payer object already in the Payment Order creation request, as an alternative to consumerProfileRef.

warning

Bank ID authentication required

In order to use the Merchant Authenticated Consumer feature, you need a legal agreement with Swedbank Pay which mandates that the consumer identified by the nationalIdentifier is authenticated with Bank ID prior to the request.

An example of how a Merchant Authenticated Consumer request looks like is provided below (abbreviated for brevity):

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "paymentorder": {
        "payer": {
            "nationalIdentifier": {
                "socialSecurityNumber": "199710202392",
                "countryCode": "SE"
            }
        }
    }
}
Required Field Type Description
check paymentorder object The payment order object.
  └➔ payer object The payer object containing information about the payer relevant for the payment order.
  └─➔ nationalIdentifier string The national identifier object.
  └──➔ socialSecurityNumber string The consumers social security number. Must be part of what you get from your authentication process.
  └──➔ countryCode string The countrycode of the consumer.

When the consumer is authenticated by the Merchant, some payment instruments will allow a more frictionless payment process. Invoice One-Click payments does not require the last 4/5 digits in the payer’s social security number (SSN), for instance.

Below you can see an example of how the payment window looks like with and without Merchant Authenticated Consumer. To the left, the SSN is removed altogether because the payer is authenticated by the Merchant, and to the right the last 4/5 digits of the SSN required as usual.

One-Click Payments without SSN Payments with SSN

Merchant Identified Payer

Merchant Identified Payer should be used if you want to use Swedbank Pay’s Payment Menu in one or more channels. If you want to use the Payment Menu in all channels, you only need to implement the use of the parameter payerReference. That should identify the payer in your system. Swedbank Pay will then ask the payer if they want to store their payment information for later use and then store this information linked to the payerReference transmitted with the Purchase request.

If you want to use Swedbank Pay Payment Menu in some channels like web and build your own in other channels like in-app you should also use this functionality. But when making your own menu you will need to look up the different payment tokens (paymentToken or recurrenceToken) linked to the specific payerReference. You should always look up this information for each payment as the payer can have added new payment information through the a web interface since the last time the app was used.

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
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",
    "payerReference": "AB1234",
    "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",
    },
    "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
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 Transferedamount - 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:

  1. You can use information generated by your system (you will have to set a unique payeeReference when you make the transaction), or
  2. 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 to OrderId in the reconciliation file.
  • capture.transaction.number returned from Swedbank Pay is equal to TransactionNo 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

Option B: You will handle the settlement process yourself

Split Settlement

The prefix split is the easy way of doing settlements for companies with multiple sub merchants. With only a few easy steps, you can make the settlement process 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 prefix numbers to sub merchants selling their goods or services through the company. The prefix number is used to match the transactions and the merchant, so the settlement is automatically split between the sub merchants. If you run a site selling tickets to concerts, theatres, sporting events etc., each venue gets its own prefix number. If you run a funeral home, the sub merchants can be everything from flower delivery to charities.

What we need from you as a company

  • Send us a KYC 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 at your website or in your app a unique prefix number. This needs to be included in the KYC form you send to us. We recommend using the same customer number they have in your system.
  • Attach the prefix 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 the automatic deduction of revenue cuts and fees.

How it works

  1. We set up the sub merchant prefix in our systems.
  2. The prefix number is added in the subsite field in the API call when you create the payment for the goods or service.
  3. The customer selects payment instrument and completes the payment.
  4. The payment goes into the client funds account.
  5. Swedbank Pay matches the transaction and the merchant using the prefix number.
  6. The settlement is split and connected to the correct merchant.
  7. Revenue cuts for the super merchant and fees from Swedbank Pay are deducted automatically.
  8. Payout to the sub merchant is done.

The upsides

  • Since the sub merchants are connected to Swedbank Pay through the super merchant instead of having separate setups, this means that you:
  • Only need one agreement for credit card, Vipps, Swish, MobilePay, invoice and payment gateway.
  • Only need one acquiring agreement.
  • Only need one Vipps/Swish certificate.
  • Can add more payment instruments easily, as it only has to be done once.
  • Can set up new sub merchants quickly, as the only thing needed is a KYC form and a prefix 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 prefix split is available with 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 prefix. 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.

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
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"
        }
    }
}
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
└─➔ 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 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).

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 refreshed.

info

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.

info

Your integration must be resilient to change. Properties, operations, headers, etc., that aren’t understood in any response must be ignored. Don’t expect a specific order of elements. When in doubt, please follow the robustness principle.