Digital Payments – Payment Request v3.1

The integration consists of three main steps. Creating the payment order, displaying the payment menu, and capturing the funds. In addition, there are other post-purchase options you need. We get to them later on.

Create Payment Order

When your customer has initiated a purchase, you need to create a payment order. Start by performing a POST request towards the paymentorder resource with payer information and a completeUrl.

The productName field has been removed in v3.1, and you identify the paymentOrder version as v3.1 in the header instead.

POST, PATCH, GET and PUT requests use this header:

Content-Type: application/json;version=3.1

GET requests can also use this header:

Accept: application/json;version=3.1

Valid versions are 3.1, 3.0 and 2.0. If you do not add a version, the request will default to 2.0. Using the productName and setting it to checkout3 will default to 3.0.

To accompany the new version, we have also added a v3.1 post-purchase section, v3.1 callback, a new resource model for failedPostPurchaseAttempts and additions to the history resource model.

Supported features for this integration are subscriptions (recur, one-click and unscheduled MIT), MOTO, instrument mode, split settlement (subsite) and the possibility to use your own logo.

There is also a guest mode option for the payers who don’t wish to store their information. The way to trigger this is to not include the payerReference field in your paymentOrder request. If the payer field is included in your request, you can find the payerReference there.

Sometimes you might need to abort purchases. An example could be if a payer does not complete the purchase within a reasonable timeframe. For those instances we have abort, which you can read about in the core features. You can only use abort if the payer has not completed an authorize or a sale. If the payer is performing an action at a 3rd party, like the MobilePay, Swish or Vipps apps, abort is unavailable.

To avoid unnecessary calls, we recommend doing a GET on your paymentOrder to check if abort is an available operation before performing it.

To minimize the risk for a challenge request (Strong Customer Authentication – “SCA”) on card payments, it’s recommended that you add as much data as possible to the riskIndicator object in the request below.

GDPR: GDPR sensitive data such as email, phone numbers and social security numbers must not be used directly in request fields such as payerReference. If it is necessary to use GDPR sensitive data, it must be hashed and then the hash can be used in requests towards Swedbank Pay.

Payment Order Request

Request

1
2
3
4

POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.1

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

{
    "paymentorder": {
        "operation": "Purchase",
        "currency": "SEK",
        "amount": 1500,
        "vatAmount": 375,
        "description": "Test Purchase",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "instrument": null,
        "urls": {
            "hostUrls": [ "https://example.com", "https://example.net" ], //Seamless View only
            "paymentUrl": "https://example.com/perform-payment", //Seamless View only
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-cancelled", //Redirect only
            "callbackUrl": "https://api.example.com/payment-callback",
            "logoUrl": "https://example.com/logo.png" //Redirect only
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "AB832",
            "payeeName": "Merchant1",
            "orderReference": "or-123456"
        }
    }
}

Show fields

Field	Type	Description
`paymentOrder`	`object`	The payment order object.
`operation`	`string`	Determines the initial operation, defining the type of payment order created.
`currency`	`string`	The currency of the payment.
`amount`	`integer`	The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: `10000` = `100.00` SEK, `5000` = `50.00` SEK. The amount displayed is the final amount the payer paid for their order, including any instrument specific discounts or fees.
`vatAmount`	`integer`	The payment’s VAT (Value Added Tax) `amount`, entered in the lowest monetary unit of the selected currency. E.g.: `10000` = `100.00` SEK, `5000` = `50.00` SEK. The `vatAmount` entered will not affect the `amount` shown on the payment page, which only shows the total `amount`. This field is used to specify how much of the total `amount` the VAT will be. Set to `0` (zero) if there is no VAT `amount` charged.
`description`	`string`	The description of the payment order.
`userAgent`	`string`	The user agent of the payer. Should typically be set to the value of the `User-Agent` header sent by the payer’s web browser.
`language`	`string`	The language of the payer.
`instrument`	`string`	Only used for instrument mode. Set the field to the payment instrument you wish to display. If no instrument is specified, the full payment menu will be displayed.
`implementation`	`string`	Indicates which implementation to use.
`urls`	`object`	The `urls` object, containing the URLs relevant for the payment order.
`hostUrls`	`array`	The array of URLs valid for embedding of Swedbank Pay Seamless Views.
`paymentUrl`	`string`	The `paymentUrl` represents the URL that Swedbank Pay will redirect back to when the view-operation needs to be loaded, to inspect and act on the current status of the payment, such as when the payer is redirected out of the Seamless View (the `<iframe>`) and sent back after completing the payment. `paymentUrl` is only used in Seamless Views and should point to the page of where the Payment Order Seamless View is hosted. If both `cancelUrl` and `paymentUrl` is sent, the `paymentUrl` will used. Trustly will only be available if the `paymentUrl` is provided while using Seamless View. With Redirect Trustly will appear regardless.
`completeUrl`	`string`	The URL that Swedbank Pay will redirect back to when the payer has completed their interactions with the payment. This does not indicate a successful payment, only that it has reached a final (complete) state. A `GET` request needs to be performed on the payment order to inspect it further. See `completeUrl` for details.
`cancelUrl`	`string`	The URL to redirect the payer to if the payment is cancelled, either by the payer or by the merchant trough an `abort` request of the `payment` or `paymentorder`.
`callbackUrl`	`string`	The URL that Swedbank Pay will perform an HTTP `POST` against every time a transaction is created on the payment order. See callback for details.
`logoUrl`	`string`	With permission and activation on your contract, sending in a `logoUrl` will replace the Swedbank Pay logo with the logo sent in. If you do not send in a `logoUrl`, then no logo and no text is shown. Without permission or activation on your contract, sending in a `logoUrl` has no effect. Read more about this in Custom Logo.
`payeeInfo`	`object`	The `payeeInfo` object, containing information about the payee (the recipient of the money). See `payeeInfo` for details.
`payeeId`	`string`	The ID of the payee, usually the merchant ID.
`payeeReference`	`string`	A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the `transaction.number` or the `payeeReference` is sent to the acquirer. If Swedbank Pay handles the settlement, the `transaction.number` is sent and the `payeeReference` must be in the format of `A-Za-z0-9` and `string(30)`. If you handle the settlement, Swedbank Pay will send the `payeeReference` and it will be limited to the format of `string(12)`. All characters must be digits. In Invoice Payments `payeeReference` is used as an invoice/receipt number, if the `receiptReference` is not defined.
`payeeName`	`string`	The name of the payee, usually the name of the merchant.
`orderReference`	`string(50)`	The order reference should reflect the order reference found in the merchant’s systems.

Payment Order Response

Response

1
2
3

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.1
api-supported-versions: 2.0, 3.0, 3.1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

{
    "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",
        "status": "Initialized",
        "currency": "SEK",
        "vatAmount": 375,
        "amount": 1500,
        "description": "Test Purchase",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "language": "sv-SE",
        "availableInstruments": [
          "CreditCard",
          "Invoice-PayExFinancingSe",
          "Invoice-PayMonthlyInvoiceSe",
          "Swish",
          "CreditAccount",
          "Trustly" ],
        "implementation": "PaymentsOnly",  
        "instrumentMode": false,
        "guestMode": false,
        "orderItems": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/orderitems"
        },
        "urls": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/urls"
        },
        "payeeInfo": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payeeinfo"
        },
        "payer": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payers"
        },
        "history": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/history"
        },
        "failed": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/failed"
        },
        "aborted": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/aborted"
        },
        "paid": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/paid"
        },
        "cancelled": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/cancelled"
        },
        "reversed": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/reversed"
        },
        "financialTransactions": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/financialtransactions"
        },
        "failedAttempts": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/failedattempts"
        },
        "postPurchaseFailedAttempts": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/failedattempts"
        },
        "metadata": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/metadata"
        }
      },
    "operations": [
        {
          "method": "GET",
          "href": "https://ecom.externalintegration.payex.com/payment/menu/5a17c24e-d459-4567-bbad-aa0f17a76119?_tc_tid=30f2168171e142d38bcd4af2c3721959",
          "rel": "redirect-checkout",
          "contentType": "text/html"
        },
        {
          "method": "GET",
          "href": "https://ecom.externalintegration.payex.com/payment/core/js/px.payment.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119&culture=nb-NO&_tc_tid=30f2168171e142d38bcd4af2c3721959",
          "rel": "view-checkout",
          "contentType": "application/javascript"
        },
        {
          "href": "https://api.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
          "rel":"update-order",
          "method":"PATCH",
          "contentType":"application/json"
        },
        {
          "href": "https://api.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
          "rel": "abort",
          "method": "PATCH",
          "contentType": "application/json"
        }
       ]
      }

Show fields

Field	Type	Description
`paymentOrder`	`object`	The payment order object.
`id`	`string`	The relative URL and unique identifier of the `paymentorder` resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
`created`	`string`	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`
`status`	`string`	Indicates the payment order’s current status. `Initialized` is returned when the payment is created and still ongoing. The request example above has this status. `Paid` is returned when the payer has completed the payment successfully. See the `Paid` response. `Failed` is returned when a payment has failed. You will find an error message in the `Failed` response. `Cancelled` is returned when an authorized amount has been fully cancelled. See the `Cancelled` response. It will contain fields from both the cancelled description and paid section. `Aborted` is returned when the merchant has aborted the payment, or if the payer cancelled the payment in the redirect integration (on the redirect page). See the `Aborted` response.
`currency`	`string`	The currency of the payment order.
`amount`	`integer`	The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: `10000` = `100.00` SEK, `5000` = `50.00` SEK. The amount displayed is the final amount the payer paid for their order, including any instrument specific discounts or fees.
`vatAmount`	`integer`	The payment’s VAT (Value Added Tax) `amount`, entered in the lowest monetary unit of the selected currency. E.g.: `10000` = `100.00` SEK, `5000` = `50.00` SEK. The `vatAmount` entered will not affect the `amount` shown on the payment page, which only shows the total `amount`. This field is used to specify how much of the total `amount` the VAT will be. Set to `0` (zero) if there is no VAT `amount` charged.
`description`	`string(40)`	A 40 character length textual description of the purchase.
`initiatingSystemUserAgent`	`string`	The user agent of the HTTP client making the request, reflecting the value sent in the `User-Agent` header with the initial `POST` request which created the Payment Order.
`language`	`string`	`sv-SE`, `nb-NO`, `da-DK`, `en-US` or `fi-FI`.
`availableInstruments`	`string`	A list of instruments available for this payment.
`implementation`	`string`	The merchant’s Digital Payments implementation type. `Enterprise` or `PaymentsOnly`. We ask that you don’t build logic around this field’s response. It is mainly for information purposes, as the implementation types might be subject to name changes. If this should happen, updated information will be available in this table.
`integration`	`string`	The merchant’s Digital Payments integration type. `HostedView` (Seamless View) or `Redirect`. This field will not be populated until the payer has opened the payment UI, and the client script has identified if Swedbank Pay or another URI is hosting the container with the payment iframe. We ask that you don’t build logic around this field’s response. It is mainly for information purposes. as the integration types might be subject to name changes, If this should happen, updated information will be available in this table.
`instrumentMode`	`bool`	Set to `true` or `false`. Indicates if the payment is initialized with Instrument Mode (only one payment instrument available).
`guestMode`	`bool`	Set to `true` or `false`. Indicates if the payer chose to pay as a guest or not. When using the Payments Only implementation, this is triggered by not including a `payerReference` in the original `paymentOrder` request.
`orderItems`	`id`	The URL to the `orderItems` resource where information about the order items can be retrieved.
`urls`	`id`	The URL to the `urls` resource where all URLs related to the payment order can be retrieved.
`payeeInfo`	`id`	The URL to the `payeeInfo` resource where information related to the payee can be retrieved.
`payer`	`id`	The URL to the `payer` resource where information about the payer can be retrieved.
`history`	`id`	The URL to the `history` resource where information about the payment’s history can be retrieved.
`failed`	`id`	The URL to the `failed` resource where information about the failed transactions can be retrieved.
`aborted`	`id`	The URL to the `aborted` resource where information about the aborted transactions can be retrieved.
`paid`	`id`	The URL to the `paid` resource where information about the paid transactions can be retrieved.
`cancelled`	`id`	The URL to the `cancelled` resource where information about the cancelled transactions can be retrieved.
`reversed`	`id`	The URL to the `reversed` resource where information about the reversed transactions can be retrieved.
`financialTransactions`	`id`	The URL to the `financialTransactions` resource where information about the financial transactions can be retrieved.
`failedAttempts`	`id`	The URL to the `failedAttempts` resource where information about the failed attempts can be retrieved.
`postPurchaseFailedAttempts`	`id`	The URL to the `postPurchaseFailedAttempts` resource where information about the failed capture, cancel or reversal attempts can be retrieved.
`metadata`	`id`	The URL to the `metadata` resource where information about the metadata can be retrieved.
`operations`	`array`	The array of operations that are possible to perform on the payment order in its current state.

Adding To Your Request

The request shown above includes what you need to create the payment, but you can add more sections if you need or want.

Examples can be to include order items by adding a separate node, or provide risk indicators and information about the payer to make the payment process as frictionless as possible.

Read more about possible additions to the request in our feature section.