Get Started

Payment Request

How to create payments when using our Checkout.

Link to older versions

*Recommended version

Payment order v3.1

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

Before You Start

Both the payment request and other API calls are available and ready to use in our collection of Online Payment APIs. You can use the collection with your own test account or with the provided generic test merchant.

Depending on what you plan to include in your offering, we recommend stopping by the pages specific to each payment method.

Some of them – like the digital wallets Apple Pay, Click to Pay and Google Pay – have steps which must be completed before the payment method can be activated.

For Swish and Trustly, we provide useful integration recommendations.

Create Payment Order v3.1

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.

POST, PATCH, GET and PUT requests use this header for v3.1:

Content-Type: application/json;version=3.1

GET requests can also use this header:

Accept: application/json;version=3.1

The productName field has been removed in v3.1, so the only way of specifying that you are using v3.1 is through the header.

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 payment operations. 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.

GDPR

When adding information to the Payer object for the purpose of pre-filling or storing any data connected to the payer, you must first obtain their explicit consent. In general, this consent can be collected when the payer provides their delivery information, such as during the checkout or registration process.

Examples of such fields include:

  • firstName
  • lastName
  • email
  • MSISDN

If you are linking payer information to a profile (payerReference) or using stored credentials for express checkouts, do not use sensitive identifiers — such as email addresses, phone numbers, or social security numbers—in fields like payerReference. These fields are not intended to hold personal data, and therefore do not offer the same level of protection or processing safeguards as fields explicitly designed for sensitive information under GDPR.

If the use of sensitive data is absolutely necessary, it must be hashed before being sent in any request to Swedbank Pay. The hash must be meaningful only to you, the merchant or integrator, and does not need to be reversible by Swedbank Pay. This means you are solely responsible for generating the hash and, if needed, securely mapping it back to the original data on your side. The responsibility for ensuring the lawful processing, protection, and handling of personal data — both during and after the transaction — rests entirely with you.

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.

Top of page

Payment Order Request v3.1

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",
        "urls": {
            "hostUrls": [ "https://example.com", "https://example.net" ],
            "paymentUrl": "https://example.com/perform-payment", //Seamless View only
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-cancelled", //Redirect only
            "callbackUrl": "https://api.example.com/payment-callback",
            "logoUrl": "https://example.com/logo.png",
            "termsOfServiceUrl": "https://example.com/termsandconditoons.pdf"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "AB832",
            "payeeName": "Merchant1",
            "orderReference": "or-123456"
        }
    }
}
Field
Type
Required
paymentOrder object check
The payment order object.
operation string check

Determines the initial operation, defining the type of payment order created. Possible options are Purchase, Abort Verify, UnscheduledPurchase, Recur and Payout.

currency string check
The currency of the payment.
amount integer check

The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The amount displayed is the final amount the payer paid for their order, including any payment method specific discounts or fees.

vatAmount integer check

The payment’s VAT (Value Added Tax) amount, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The vatAmount entered will not affect the amount shown on the payment page, which only shows the total amount. This field is used to specify how much of the total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.

description string(40) check
Human-readable description for the payment order.
userAgent string check

The user agent of the payer. Should typically be set to the value of the User-Agent header sent by the payer’s web browser.

language string(5) check

sv-SE, nb-NO, da-DK, en-US or fi-FI.

implementation string
Indicates which implementation to use.
urls object check
The urls object, containing the URLs relevant for the payment order.
hostUrls array check
The array of valid host URLs.
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. When using Redirect, Trustly will appear regardless.

completeUrl string check

The URL that Swedbank Pay will redirect back to when the payer has completed their interactions with the payment. This does not indicate a successful payment, only that it has reached a final (complete) state. A GET request needs to be performed on the payment order to inspect it further. See completeUrl for details.

cancelUrl string check
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 check

The URL that Swedbank Pay will perform an HTTP POST against every time a transaction is created on the payment order. See callback for details.

logoUrl string

With permission and activation on your contract (if you are using Seamless View), sending in a logoUrl will replace the Swedbank Pay logo with the logo sent in. If you do not send in a logoUrl, then no logo and no text is shown. Without permission or activation on your contract, sending in a logoUrl has no effect. The logo must be a picture with maximum 50px height and 400px width. Requires HTTPS. Read more about this in Custom Logo .

termsOfServiceUrl string

The URL to the terms of service document which the payer must accept in order to complete the payment. HTTPS is a requirement.

payeeInfo object check

The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details.

payeeId string check
The ID of the payee, usually the merchant ID.
payeeReference string(50) check

A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent to the acquirer and the payeeReference must be in the format of A-Za-z0-9 and string(30). If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12). All characters must be digits. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.

payeeName string
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.

Top of page

Payment Order Response v3.1

Response 



1
2
3



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





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



{
    "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"
        },
        {
          "href": "https://api.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
          "rel": "abort-paymentattempt",
          "method": "PATCH",
          "contentType": "application/json"
        }
    ]
}
Field
Type
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

Determines the initial operation, defining the type of payment order created. Possible options are Purchase, Abort Verify, UnscheduledPurchase, Recur and Payout.

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 payment method 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 textual description of the purchase. Maximum length is 40 characters.

initiatingSystemUserAgent string

The user agent of the HTTP client making the request, reflecting the value sent in the User-Agent header with the initial POST request which created the Payment Order.

language string

sv-SE, nb-NO, da-DK, en-US or fi-FI.

availableInstruments string
A list of payment methods available for this payment.
implementation string
The merchant's Online 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 Online Payments integration type. HostedView (Seamless View) or Redirect. This field will not be populated until the payer has opened the payment UI…
instrumentMode bool
Set to true or false. Indicates if the payment is initialized with Instrument Mode (only one payment method 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 object
The id for the orderItems resource where information about the order items can be retrieved.
urls object
The id for the urls resource where all URLs related to the payment order can be retrieved.
payeeInfo object
The id for the payeeInfo resource where information related to the payee can be retrieved.
payer object
The id for the payer resource where information about the payer can be retrieved.
history object
The id for the history resource where information about the payment's history can be retrieved.
failed object
The id for the failed resource where information about the failed transactions can be retrieved.
aborted object
The id for the aborted resource where information about the aborted transactions can be retrieved.
paid object
The id for the paid resource where information about the paid transactions can be retrieved.
cancelled object
The id for the cancelled resource where information about the cancelled transactions can be retrieved.
reversed object
The id for the cancelled resource where information about the reversed transactions can be retrieved.
financialTransactions object
The id for the financialTransactions resource where information about the financial transactions can be retrieved.
failedAttempts object
The id for the failedAttempts resource where information about the failed attempts can be retrieved.
postPurchaseFailedAttempts object
The id for the postPurchaseFailedAttempts resource where information about the failed capture, cancel or reversal attempts can be retrieved.
metadata object
The id for 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.

Top of page

Adding To Your Request v3.1

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.

Top of page

If you hesitate which version to use, we recommend the version marked with *.

Payment order v3.0

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

Before You Start

Both the payment request and other API calls are available and ready to use in our collection of Online Payment APIs. You can use the collection with your own test account or with the provided generic test merchant.

Depending on what you plan to include in your offering, we recommend stopping by the pages specific to each payment method.

Some of them – like the digital wallets Apple Pay, Click to Pay and Google Pay – have steps which must be completed before the payment method can be activated.

For Swish and Trustly, we provide useful integration recommendations.

Create Payment Order v3.0

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.

POST, PATCH and PUT requests use this header for v3.0:

Content-Type: application/json;version=3.0

GET requests use this header:

Accept: application/json;version=3.0

We have added productName to the payment order request in this integration. You can find it in the paymentorder field. This is no longer required, but is an option to use v3.0 of Online Payments. To use productName, simply put Checkout3 as the value in that field in the request. If you specify version in the header, you can leave out the productName field.

When productName is set to checkout3, digitalProducts will be set to false by default.

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 payment operations. 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.

GDPR

When adding information to the Payer object for the purpose of pre-filling or storing any data connected to the payer, you must first obtain their explicit consent. In general, this consent can be collected when the payer provides their delivery information, such as during the checkout or registration process.

Examples of such fields include:

  • firstName
  • lastName
  • email
  • MSISDN

If you are linking payer information to a profile (payerReference) or using stored credentials for express checkouts, do not use sensitive identifiers — such as email addresses, phone numbers, or social security numbers—in fields like payerReference. These fields are not intended to hold personal data, and therefore do not offer the same level of protection or processing safeguards as fields explicitly designed for sensitive information under GDPR.

If the use of sensitive data is absolutely necessary, it must be hashed before being sent in any request to Swedbank Pay. The hash must be meaningful only to you, the merchant or integrator, and does not need to be reversible by Swedbank Pay. This means you are solely responsible for generating the hash and, if needed, securely mapping it back to the original data on your side. The responsibility for ensuring the lawful processing, protection, and handling of personal data — both during and after the transaction — rests entirely with you.

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.

Top of page

Payment Order Request v3.0

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.0     // Version optional





1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26



{
    "paymentorder": {
        "operation": "Purchase",
        "currency": "SEK",
        "amount": 1500,
        "vatAmount": 375,
        "description": "Test Purchase",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "productName": "Checkout3", // Removed in 3.1, can be excluded in 3.0 if version is added in header
        "urls": {
            "hostUrls": [ "https://example.com", "https://example.net" ],
            "paymentUrl": "https://example.com/perform-payment", //Seamless View only
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-cancelled", //Redirect only
            "callbackUrl": "https://api.example.com/payment-callback",
            "logoUrl": "https://example.com/logo.png"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "AB832",
            "payeeName": "Merchant1",
            "orderReference": "or-123456"
        }
    }
}
Field
Type
Required
paymentOrder object check
The payment order object.
operation string check

Determines the initial operation, defining the type of payment order created. Possible options are Purchase, Abort Verify, UnscheduledPurchase, Recur and Payout.

currency string check
The currency of the payment.
amount integer check

The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The amount displayed is the final amount the payer paid for their order, including any payment method specific discounts or fees.

vatAmount integer check

The payment’s VAT (Value Added Tax) amount, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The vatAmount entered will not affect the amount shown on the payment page, which only shows the total amount. This field is used to specify how much of the total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.

description string(40) check
Human-readable description for the payment order.
userAgent string check

The user agent of the payer. Should typically be set to the value of the User-Agent header sent by the payer’s web browser.

language string(5) check

sv-SE, nb-NO, da-DK, en-US or fi-FI.

productName string check
Used to tag the payment as Online Payments v3.0. Mandatory for Online Payments v3.0, either in this field or the header, as you won't get the operations in the response without submitting this field.
implementation string
Indicates which implementation to use.
urls object check
The urls object, containing the URLs relevant for the payment order.
hostUrls array check
The array of valid host URLs.
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. When using Redirect, Trustly will appear regardless.

completeUrl string check

The URL that Swedbank Pay will redirect back to when the payer has completed their interactions with the payment. This does not indicate a successful payment, only that it has reached a final (complete) state. A GET request needs to be performed on the payment order to inspect it further. See completeUrl for details.

cancelUrl string check
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 check

The URL that Swedbank Pay will perform an HTTP POST against every time a transaction is created on the payment order. See callback for details.

logoUrl string

With permission and activation on your contract (if you are using Seamless View), sending in a logoUrl will replace the Swedbank Pay logo with the logo sent in. If you do not send in a logoUrl, then no logo and no text is shown. Without permission or activation on your contract, sending in a logoUrl has no effect. The logo must be a picture with maximum 50px height and 400px width. Requires HTTPS. Read more about this in Custom Logo .

orderItems array check

The array of items being purchased with the order. Note that authorization orderItems will not be printed on invoices, so lines meant for print must be added in the Capture request. The authorization orderItems will, however, be used in the Merchant Portal when captures or reversals are performed, and might be shown other places later. It is required to use this field to be able to send Capture orderItems. Capture requests should only contain items meant to be captured from the order.

reference string check
A reference that identifies the order item.
name string check
The name of the order item.
type enum check
PRODUCT, SERVICE, SHIPPING_FEE, DISCOUNT, VALUE_CODE, or OTHER. The type of the order item.
class string check
The classification of the order item. Can be used for assigning the order item to a specific product category, such as MobilePhone. Note that class cannot contain spaces and must follow the regex pattern [\w-]*. Swedbank Pay may use this field for statistics.
itemUrl string
The URL to a page that can display the purchased item, such as a product page
imageUrl string
The URL to an image of the order item.
description string
The human readable description of the order item.
discountDescription string
The human readable description of the possible discount.
quantity number check
The 4 decimal precision quantity of order items being purchased.
quantityUnit string check
The unit of the quantity, such as pcs, grams, or similar.
unitPrice integer check
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.
vatPercent integer check
The percent value of the VAT multiplied by 100, so 25% becomes 2500.
amount integer check

The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The amount displayed is the final amount the payer paid for their order, including any payment method specific discounts or fees.

vatAmount integer check

The payment’s VAT (Value Added Tax) amount, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The vatAmount entered will not affect the amount shown on the payment page, which only shows the total amount. This field is used to specify how much of the total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.

payeeInfo object check

The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details.

payeeId string check
The ID of the payee, usually the merchant ID.
payeeReference string(50) check

A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent to the acquirer and the payeeReference must be in the format of A-Za-z0-9 and string(30). If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12). All characters must be digits. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.

payeeName string
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.

Top of page

Payment Order Response v3.0

Response 



1
2
3



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





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



{
    "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,
        "payer": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/payers"
        },
        "orderItems": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/orderitems"
        },
        "history": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/history"
        },
        "failed": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/failed"
        },
        "aborted": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/aborted"
        },
        "paid": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/paid"
        },
        "cancelled": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/cancelled"
        },
        "financialTransactions": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/financialtransactions"
        },
        "failedAttempts": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/failedattempts"
        },
        "metadata": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/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/222a50ca-b268-4b32-16fa-08d6d3b73224",
          "rel":"update-order",
          "method":"PATCH",
          "contentType":"application/json"
        },
        {
          "href": "https://api.payex.com/psp/paymentorders/222a50ca-b268-4b32-16fa-08d6d3b73224",
          "rel": "abort",
          "method": "PATCH",
          "contentType": "application/json"
        },
        {
          "href": "https://api.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
          "rel": "abort-paymentattempt",
          "method": "PATCH",
          "contentType": "application/json"
        }
       ]
      }
Field
Type
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

Determines the initial operation, defining the type of payment order created. Possible options are Purchase, Abort Verify, UnscheduledPurchase, Recur and Payout.

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 payment method 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 textual description of the purchase. Maximum length is 40 characters.

initiatingSystemUserAgent string

The user agent of the HTTP client making the request, reflecting the value sent in the User-Agent header with the initial POST request which created the Payment Order.

language string

sv-SE, nb-NO, da-DK, en-US or fi-FI.

availableInstruments string
A list of methods available for this payment.
implementation string
The merchant's Online 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 Online 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 method 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 object
The id for the orderItems resource where information about the order items can be retrieved.
urls object
The id for the urls resource where all URLs related to the payment order can be retrieved.
payeeInfo object
The id for the payeeInfo resource where information related to the payee can be retrieved.
payer object
The id for the payer resource where information about the payer can be retrieved.
history object
The id for the history resource where information about the payment's history can be retrieved.
failed object
The id for the failed resource where information about the failed transactions can be retrieved.
aborted object
The id for the aborted resource where information about the aborted transactions can be retrieved.
paid object
The id for the paid resource where information about the paid transactions can be retrieved.
cancelled object
The id for the cancelled resource where information about the cancelled transactions can be retrieved.
reversed object
The id for the cancelled resource where information about the reversed transactions can be retrieved.
financialTransactions object
The id for the financialTransactions resource where information about the financial transactions can be retrieved.
failedAttempts object
The id for the failedAttempts resource where information about the failed attempts can be retrieved.
postPurchaseFailedAttempts object
The id for the postPurchaseFailedAttempts resource where information about the failed capture, cancel or reversal attempts can be retrieved.
metadata object
The id for 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.

Top of page

Adding To Your Request v3.0

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.

Top of page