Get Started

Post-Purchase

When the payer has completed the purchase, you need to implement the relevant post-purchase operations in your order system. These operations, and how they are executed, are described below.

Link to older versions

*Recommended version

Payment order v3.1

Two-phase payments: When dealing in physical goods using two-phase payment methods, all goods must be shipped before you capture the authorized amount. This is regulated in part by the Swedish Distance and Doorstep Sales Act, required in our terms and (for card payments) required by Visa and Mastercard.

When something goes wrong: When something fails during a post-purchase operation, you will get an error message in the response in the form of a problem json.

See examples of the jsons in the problems section.

Capture v3.1

Captures are only possible when a payment has a successful Authorization transaction, naturally excluding one-phase payment methods like Swish and Trustly. They will be marked as a Sale transaction. Two-phase payment methods like card and Vipps however, require a Capture to be completed.

Please note that you have a maximum of 5 consecutive failed attempts at a capture. The payment will be locked after the fifth, and you need to contact us for further attempts.

In addition to full captures, it is possible to do partial captures of the authorized amount. You can do more captures on the same payment later, up to the total authorized amount. A useful tool for when you have to split orders into several shipments.

First off, you must request the order information from the server to get the request link. With this, you can request the capture with the amount to capture, and get the status back.

To capture the authorized payment, we need to perform capture against the accompanying href returned in the operations list. See the abbreviated request and response below:

Top of page

Capture Request v3.1

Request 



1
2
3
4



POST /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/captures HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.1





1
2
3
4
5
6
7
8
9



{
    "transaction": {
        "description": "Capturing the authorized payment",
        "amount": 1500,
        "vatAmount": 375,
        "payeeReference": "AB832",
        "receiptReference": "AB831"
    }
}
Required Field Type Description
check transaction object The transaction object.
check description string The description of the capture transaction.
check amount integer The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The amount displayed is the final amount the payer paid for their order, including any payment method specific discounts or fees.
check vatAmount integer The payment’s VAT (Value Added Tax) amount, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The vatAmount entered will not affect the amount shown on the payment page, which only shows the total amount. This field is used to specify how much of the total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.
check payeeReference string(30) A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent to the acquirer and the payeeReference must be in the format of A-Za-z0-9 and string(30). If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12). All characters must be digits. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.
  receiptReference string(30) A unique reference to the transaction, provided by the merchant. Can be used as an invoice or receipt number as a supplement to payeeReference.
check orderItems array 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.
check reference string A reference that identifies the order item.
check name string The name of the order item.
check type enum PRODUCT, SERVICE, SHIPPING_FEE, PAYMENT_FEE, DISCOUNT, VALUE_CODE or OTHER. The type of the order item.
check class string The classification of the order item. Can be used for assigning the order item to a specific product category, such as MobilePhone. Note that class cannot contain spaces and must follow the regex pattern [\w-]*. Swedbank Pay may use this field for statistics.
  itemUrl string The URL to a page that can display the purchased item, product or similar.
︎︎︎ imageUrl string The URL to an image of the order item.
  description string The human readable description of the order item.
  discountDescription string The human readable description of the possible discount.
check quantity number The 4 decimal precision quantity of order items being purchased.
check quantityUnit string The unit of the quantity, such as pcs, grams, or similar. This is used for your own book keeping.
check unitPrice integer The price per unit of order item, including VAT.
  discountPrice integer If the order item is purchased at a discounted price. This field should contain that price, including VAT.
check vatPercent integer The percent value of the VAT multiplied by 100, so 25% becomes 2500.
check amount integer The total amount including VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 SEK and 5000 equals 50.00 SEK.
check vatAmount integer The total amount of VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 SEK and 5000 equals 50.00 SEK.
check reference string A reference that identifies the order item.
check name string The name of the order item.
check type enum PRODUCT, SERVICE, SHIPPING_FEE, PAYMENT_FEE, DISCOUNT, VALUE_CODE or OTHER. The type of the order item.
check class string The classification of the order item. Can be used for assigning the order item to a specific product category, such as MobilePhone. Note that class cannot contain spaces and must follow the regex pattern [\w-]*. Swedbank Pay may use this field for statistics.
︎︎︎ itemUrl string The URL to a page that can display the purchased item, 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 number 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 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.

Top of page

Capture Response v3.1

If the capture request succeeds, this should be the response:

Response 



1
2
3



HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.1
api-supported-versions: 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



{
  "paymentOrder": {
    "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d",
    "created": "2020-03-03T07:19:27.5636519Z",
    "updated": "2020-03-03T07:21:00.5605905Z",
    "operation": "Purchase",
    "status": "Paid",
    "currency": "SEK",
    "amount": 1500,
    "vatAmount": 375,
    "remainingCaptureAmount": 0, // Only present after a partial capture
    "remainingCancellationAmount": 0, // Only present after a partial capture
    "remainingReversalAmount": 1500,
    "description": "Test Purchase",
    "initiatingSystemUserAgent": "<should be set by the system calling POST:/psp/paymentorders>",
    "language": "sv-SE",
    "availableInstruments": [ "CreditCard", "Invoice-PayExFinancingSe", "Invoice-PayMonthlyInvoiceSe", "Swish", "CreditAccount", "Trustly" ],
    "implementation": "PaymentsOnly",
    "integration": "HostedView|Redirect",
    "instrumentMode": false,
    "guestMode": true,
    "orderItems": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/orderitems"
    },
    "urls": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/urls"
    },
    "payeeInfo": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/payeeInfo"
    },
    "payer": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/payers"
    },
    "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"
    },
    "postPurchaseFailedAttempts": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/postpurchasefailedattempts"
    },
    "metadata": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/metadata"
    }
  },
  "operations": [
    {
      "href": "https://api.payex.com/psp/paymentorders/222a50ca-b268-4b32-16fa-08d6d3b73224/reversals",
      "rel": "reversal",
      "method": "POST",
      "contentType": "application/json"
    },
  ]
}
Property Type Description
paymentOrder string The relative URL of the payment order this capture transaction belongs to.
id string The relative URL of the created capture transaction.
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.
operation string Determines the initial operation, defining the type of payment order created. Possible options are Purchase, Abort Verify, Unscheduled, Recur and Payout.
status string Initialized, Paid, Failed, Reversed Cancelled, or Aborted. Indicates the payment order’s current status.
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.
remainingCaptureAmount integer The remaining authorized amount that is still possible to capture.
remainingCancellationAmount integer The remaining authorized amount that is still possible to cancel.
remainingReversalAmount integer The remaining captured amount that is still available for reversal.
description string 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, 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 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 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.
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. See Operations for details.

Top of page

Capture Sequence Diagram v3.1 

sequenceDiagram
    participant Merchant
    participant SwedbankPay as Swedbank Pay

    rect rgba(81,43,43,0.1)
        activate Merchant
        note left of Payer: Capture
        Merchant ->>+ SwedbankPay: rel:capture
        deactivate Merchant
        SwedbankPay -->>- Merchant: Capture status
        note right of Merchant: Capture here only if the purchased<br/>goods don't require shipping.<br/>If shipping is required, perform capture<br/>after the goods have shipped.<br>Should only be used for <br>Payment Methods that support <br>Authorizations.
    end

The purchase should now be complete. But what if the purchase is cancelled or the payer wants to return goods? For these instances, we have cancel and reversal.

Top of page

Cancel v3.1

The cancellations resource lists the cancellation transactions on a specific payment.

To cancel a previously created payment, you must perform the cancel operation against the accompanying href returned in the operations list. You can only cancel a payment - or part of a payment - which has not been captured yet. There must be funds left that are only authorized. If you cancel before any capture has been done, no captures can be performed later.

Top of page

Cancel Request v3.1

Request 



1
2
3
4



POST /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/cancellations HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.1





1
2
3
4
5
6



{
    "transaction": {
        "description": "Test Cancellation",
        "payeeReference": "ABC123"
    }
}
Required Field Type Description
check transaction object The transaction object.
check description string A textual description of why the transaction is cancelled.
check payeeReference string(30) A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent to the acquirer and the payeeReference must be in the format of A-Za-z0-9 and string(30). If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12). All characters must be digits.

Top of page

Cancel Response v3.1

If the cancel request succeeds, the response should be similar to the example below:

Response 



1
2
3



HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.1
api-supported-versions: 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



{
  "paymentOrder": {
    "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d",
    "created": "2020-03-03T07:19:27.5636519Z",
    "updated": "2020-03-03T07:21:00.5605905Z",
    "operation": "Purchase",
    "status": "Cancelled",
    "currency": "SEK",
    "amount": 1500,
    "vatAmount": 375,
    "description": "Test Purchase",
    "initiatingSystemUserAgent": "<should be set by the system calling POST:/psp/paymentorders>",
    "language": "sv-SE",
    "availableInstruments": [ "CreditCard", "Invoice-PayExFinancingSe", "Invoice-PayMonthlyInvoiceSe", "Swish", "CreditAccount", "Trustly" ],
    "implementation": "PaymentsOnly",
    "integration": "HostedView|Redirect",
    "instrumentMode": true,
    "guestMode": true,
    "orderItems": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/orderitems"
    },
    "urls": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/urls"
    },
    "payeeInfo": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/payeeInfo"
    },
    "payer": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/payers"
    },
    "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"
    },
    "postPurchaseFailedAttempts": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/postpurchasefailedattempts"
    },
    "metadata": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/metadata"
    }
  },
  "operations": [
  ]
}
Property Type Description
paymentOrder string The relative URL of the payment order this capture transaction belongs to.
id string The relative URL of the created capture transaction.
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.
operation string Determines the initial operation, defining the type of payment order created. Possible options are Purchase, Abort Verify, Unscheduled, Recur and Payout.
status string Initialized, Paid, Failed, Reversed Cancelled, or Aborted. Indicates the payment order’s current status.
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.
remainingCaptureAmount integer The remaining authorized amount that is still possible to capture.
remainingCancellationAmount integer The remaining authorized amount that is still possible to cancel.
remainingReversalAmount integer The remaining captured amount that is still available for reversal.
description string 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, 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 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 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.
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. See Operations for details.

Top of page

Cancel Sequence Diagram v3.1

Cancel can only be done on an authorized transaction. As a cancellation does not have an amount associated with it, it will release the entire reserved amount. If your intention is to make detailed handling, such as only capturing a partial amount of the transaction, you must start with the capture of the desired amount before performing a cancel for the remaining reserved funds.

sequenceDiagram
    participant SwedbankPay as Swedbank Pay

    Merchant->>SwedbankPay: POST <  cancellation>
    activate Merchant
    activate SwedbankPay
    SwedbankPay-->>Merchant: transaction resource
    deactivate SwedbankPay
    deactivate Merchant

Top of page

Reversal v3.1

This transaction is used when a Capture or Sale payment needs to be reversed.

Please note that you have a maximum of 5 consecutive failed attempts at a reversal. The payment will be locked after this, and you need to contact us for another attempt.

If the full amount of a sale transaction or a captured transaction is reversed, The transaction will now have status Reversed instead of Paid.

If we want to reverse a previously captured amount, we need to perform reversal against the accompanying href returned in the operations list.

Top of page

Reversal Request v3.1

Request 



1
2
3
4



POST /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/reversals 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



{
    "transaction": {
        "description": "Reversal of captured transaction",
        "amount": 1500,
        "vatAmount": 375,
        "payeeReference": "ABC123"
    }
}
Required Field Type Description
check transaction object The transaction object.
check amount integer The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The amount displayed is the final amount the payer paid for their order, including any payment method specific discounts or fees.
check vatAmount integer The payment’s VAT (Value Added Tax) amount, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The vatAmount entered will not affect the amount shown on the payment page, which only shows the total amount. This field is used to specify how much of the total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.
check payeeReference string(30) A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent to the acquirer and the payeeReference must be in the format of A-Za-z0-9 and string(30). If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12). All characters must be digits. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.
  receiptReference string(30) A unique reference to the transaction, provided by the merchant. Can be used as an invoice or receipt number as a supplement to payeeReference.
check description string Textual description of why the transaction is reversed.
check orderItems array 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.
check reference string A reference that identifies the order item.
check name string The name of the order item.
check type enum PRODUCT, SERVICE, SHIPPING_FEE, PAYMENT_FEE, DISCOUNT, VALUE_CODE or OTHER. The type of the order item.
check class string The classification of the order item. Can be used for assigning the order item to a specific product category, such as MobilePhone. Note that class cannot contain spaces and must follow the regex pattern [\w-]*. Swedbank Pay may use this field for statistics.
  itemUrl string The URL to a page that can display the purchased item, product or similar.
  imageUrl string The URL to an image of the order item.
  description string The human readable description of the order item.
  discountDescription string The human readable description of the possible discount.
check quantity number The 4 decimal precision quantity of order items being purchased.
check quantityUnit string The unit of the quantity, such as pcs, grams, or similar. This is used for your own book keeping.
check unitPrice integer The price per unit of order item, including VAT.
  discountPrice integer If the order item is purchased at a discounted price. This field should contain that price, including VAT.
check vatPercent integer The percent value of the VAT multiplied by 100, so 25% becomes 2500.
check amount integer The total amount including VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 SEK and 5000 equals 50.00 SEK.
check vatAmount integer The total amount of VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 SEK and 5000 equals 50.00 SEK.

Top of page

Reversal Response v3.1

If the reversal request succeeds, the response should be similar to the example below:

Response 



1
2
3



HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.1
api-supported-versions: 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



{
  "paymentOrder": {
    "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d",
    "created": "2020-03-03T07:19:27.5636519Z",
    "updated": "2020-03-03T07:21:00.5605905Z",
    "operation": "Purchase",
    "status": "Reversed",
    "currency": "SEK",
    "amount": 1500,
    "vatAmount": 375,
    "remainingCaptureAmount": 0, // Only present after a partial reversal
    "remainingReversalAmount": 0, // Only present after a partial reversal
    "description": "Test Purchase",
    "initiatingSystemUserAgent": "<should be set by the system calling POST:/psp/paymentorders>",
    "language": "sv-SE",
    "availableInstruments": [ "CreditCard", "Invoice-PayExFinancingSe", "Invoice-PayMonthlyInvoiceSe", "Swish", "CreditAccount", "Trustly" ],
    "implementation": "PaymentsOnly",
    "integration": "HostedView|Redirect",
    "instrumentMode": true,
    "guestMode": true,
    "orderItems": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/orderitems"
    },
    "urls": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/urls"
    },
    "payeeInfo": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/payeeInfo"
    },
    "payer": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/payers"
    },
    "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"
    },
    "postPurchaseFailedAttempts": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/postpurchasefailedattempts"
    },
    "metadata": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/metadata"
    }
  },
  "operations": [
  ]
}
Property Type Description
paymentOrder string The relative URL of the payment order this capture transaction belongs to.
id string The relative URL of the created capture transaction.
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.
operation string Determines the initial operation, defining the type of payment order created. Possible options are Purchase, Abort Verify, Unscheduled, Recur and Payout.
status string Initialized, Paid, Failed, Reversed Cancelled, or Aborted. Indicates the payment order’s current status.
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.
remainingCaptureAmount integer The remaining authorized amount that is still possible to capture. Only present after a partial reversal.
remainingCancellationAmount integer The remaining authorized amount that is still possible to cancel. Only present after a partial reversal.
remainingReversalAmount integer The remaining captured amount that is still available for reversal. This field will not appear in the initial response if the payment method used was Swish. It will first appear if and when you do a GET on the payment.
description string 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, 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 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 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.
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.

Done With The Basics

You have reached the final step of the basic payment implementation and should be able to validate that everything works as intended, or maybe it’s time for acceptance tests?

Some of our payment methods require a few additional steps before they can be activated and become available in your payment UI. Read more about them and what you need to do by clicking the cards below.

There are other features and capabilities you can add to tailor the payment requests in order to meet your business needs. See what else we can offer by clicking Additional Request Options.

Apple Pay

How to activate Apple Pay webflow or in-app
Click to Pay

Additional signup needed for Click to Pay
Google Pay™

Additional signup needed for Google Pay™
Trustly

How to enable Trustly Express

Top of page

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

Payment order v3.0

Two-phase payments: When dealing in physical goods using two-phase payment methods, all goods must be shipped before you capture the authorized amount. This is regulated in part by the Swedish Distance and Doorstep Sales Act, required in our terms and (for card payments) required by Visa and Mastercard.

When something goes wrong: When something fails during a post-purchase operation, you will get an error message in the response in the form of a problem json.

See examples of the jsons in the problems section.

Capture v3.0

Captures are only possible when a payment has a successful Authorization transaction, naturally excluding one-phase payment methods like Swish and Trustly. They will be marked as a Sale transaction. Two-phase payment methods like card and Vipps however, require a Capture to be completed.

Please note that you have a maximum of 5 consecutive failed attempts at a capture. The payment will be locked after the fifth, and you need to contact us for further attempts.

In addition to full captures, it is possible to do partial captures of the authorized amount. You can do more captures on the same payment later, up to the total authorized amount. A useful tool for when you have to split orders into several shipments.

First off, you must request the order information from the server to get the request link. With this, you can request the capture with the amount to capture, and get the status back.

To capture the authorized payment, we need to perform capture against the accompanying href returned in the operations list. See the abbreviated request and response below:

Top of page

Capture Request v3.0

Request 



1
2
3
4



POST /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/captures HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.0    // Version optional, can be set in `productName`





1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41



{
    "transaction": {
        "description": "Capturing the authorized payment",
        "amount": 1500,
        "vatAmount": 375,
        "payeeReference": "AB832",
        "receiptReference": "AB831",
        "orderItems": [
            {
                "reference": "P1",
                "name": "Product1",
                "type": "PRODUCT",
                "class": "ProductGroup1",
                "itemUrl": "https://example.com/products/123",
                "imageUrl": "https://example.com/product123.jpg",
                "description": "Product 1 description",
                "discountDescription": "Volume discount",
                "quantity": 4,
                "quantityUnit": "pcs",
                "unitPrice": 300,
                "discountPrice": 200,
                "vatPercent": 2500,
                "amount": 1000,
                "vatAmount": 250
            },
            {
                "reference": "P2",
                "name": "Product2",
                "type": "PRODUCT",
                "class": "ProductGroup1",
                "description": "Product 2 description",
                "quantity": 1,
                "quantityUnit": "pcs",
                "unitPrice": 500,
                "vatPercent": 2500,
                "amount": 500,
                "vatAmount": 125
            }
        ]
    }
}
Required Field Type Description
check transaction object The transaction object.
check description string The description of the capture transaction.
check amount integer The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The amount displayed is the final amount the payer paid for their order, including any payment method specific discounts or fees.
check vatAmount integer The payment’s VAT (Value Added Tax) amount, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The vatAmount entered will not affect the amount shown on the payment page, which only shows the total amount. This field is used to specify how much of the total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.
check payeeReference string(30) A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent to the acquirer and the payeeReference must be in the format of A-Za-z0-9 and string(30). If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12). All characters must be digits. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.
  receiptReference string(30) A unique reference to the transaction, provided by the merchant. Can be used as an invoice or receipt number as a supplement to payeeReference.
check orderItems array 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.
check reference string A reference that identifies the order item.
check name string The name of the order item.
check type enum PRODUCT, SERVICE, SHIPPING_FEE, PAYMENT_FEE, DISCOUNT, VALUE_CODE or OTHER. The type of the order item.
check class string The classification of the order item. Can be used for assigning the order item to a specific product category, such as MobilePhone. Note that class cannot contain spaces and must follow the regex pattern [\w-]*. Swedbank Pay may use this field for statistics.
  itemUrl string The URL to a page that can display the purchased item, product or similar.
︎︎︎ imageUrl string The URL to an image of the order item.
  description string The human readable description of the order item.
  discountDescription string The human readable description of the possible discount.
check quantity number The 4 decimal precision quantity of order items being purchased.
check quantityUnit string The unit of the quantity, such as pcs, grams, or similar. This is used for your own book keeping.
check unitPrice integer The price per unit of order item, including VAT.
  discountPrice integer If the order item is purchased at a discounted price. This field should contain that price, including VAT.
check vatPercent integer The percent value of the VAT multiplied by 100, so 25% becomes 2500.
check amount integer The total amount including VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 SEK and 5000 equals 50.00 SEK.
check vatAmount integer The total amount of VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 SEK and 5000 equals 50.00 SEK.
check reference string A reference that identifies the order item.
check name string The name of the order item.
check type enum PRODUCT, SERVICE, SHIPPING_FEE, PAYMENT_FEE, DISCOUNT, VALUE_CODE or OTHER. The type of the order item.
check class string The classification of the order item. Can be used for assigning the order item to a specific product category, such as MobilePhone. Note that class cannot contain spaces and must follow the regex pattern [\w-]*. Swedbank Pay may use this field for statistics.
︎︎︎ itemUrl string The URL to a page that can display the purchased item, 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 number 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 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.

Top of page

Capture Response v3.0

If the capture request succeeds, this should be the response:

Response 



1
2
3



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





1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18



{
    "payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "capture": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "transaction": {
            "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "created": "2020-06-22T10:56:56.2927632Z",
            "updated": "2020-06-22T10:56:56.4035291Z",
            "type": "Capture",
            "state": "Completed",
            "amount": 1500,
            "vatAmount": 375,
            "description": "Capturing the authorized payment",
            "payeeReference": "AB832",
            "receiptReference": "AB831"
        }
    }
}
Property Type Description
payment string The relative URL of the payment this capture transaction belongs to.
capture object The capture object, containing the information about the capture transaction.
id string The relative URL of the created capture transaction.
transaction object The object representation of the generic transaction resource, containing information about the current transaction.
id string The relative URL of the current transaction resource.
created string The ISO-8601 date and time of when the transaction was created.
updated string The ISO-8601 date and time of when the transaction was updated.
type string Indicates the transaction type.
state string Indicates the state of the transaction, usually initialized, completed or failed. If a partial has been done and further transactions are possible, the state will be awaitingActivity.
number integer The transaction number, useful when there’s need to reference the transaction in human communication. Not usable for programmatic identification of the transaction, where id should be used instead.
amount integer The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. 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 A textual description of the purchase. Maximum length is 40 characters.
payeeReference string(30) A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent to the acquirer and the payeeReference must be in the format of A-Za-z0-9 and string(30). If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12). All characters must be digits. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.
receiptReference string(30) A unique reference from the merchant system. It is set per operation to ensure an exactly-once delivery of a transactional operation. It is used to supplement payeeReference as an additional receipt number.

Top of page

Capture Sequence Diagram v3.0 

sequenceDiagram
    participant Merchant
    participant SwedbankPay as Swedbank Pay

    rect rgba(81,43,43,0.1)
        activate Merchant
        note left of Payer: Capture
        Merchant ->>+ SwedbankPay: rel:capture
        deactivate Merchant
        SwedbankPay -->>- Merchant: Capture status
        note right of Merchant: Capture here only if the purchased<br/>goods don't require shipping.<br/>If shipping is required, perform capture<br/>after the goods have shipped.<br>Should only be used for <br>payment methods that support <br>Authorizations.
    end

The purchase should now be complete. But what if the purchase is cancelled or

the payer wants to return goods? For these instances, we have cancel and reversal.

Top of page

Cancel v3.0

The cancellations resource lists the cancellation transactions on a

specific payment.

To cancel a previously created payment, you must perform the cancel operation against the accompanying href returned in the operations list. You can only cancel a payment - or part of a payment - which has not been captured yet. There must be funds left that are only authorized. If you cancel before any capture has been done, no captures can be performed later.

Top of page

Cancel Request v3.0

Request 



1
2
3
4



POST /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/cancellations HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.0     // Version optional, can be set in `productName`





1
2
3
4
5
6



{
    "transaction": {
        "description": "Test Cancellation",
        "payeeReference": "ABC123"
    }
}
Required Field Type Description
check transaction object The transaction object.
check description string A textual description of why the transaction is cancelled.
check payeeReference string(30) A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent to the acquirer and the payeeReference must be in the format of A-Za-z0-9 and string(30). If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12). All characters must be digits.

Top of page

Cancel Response v3.0

If the cancel request succeeds, the response should be similar to the example below:

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



{
    "payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "cancellation": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "transaction": {
            "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "created": "2022-01-31T09:49:13.7567756Z",
            "updated": "2022-01-31T09:49:14.7374165Z",
            "type": "Cancellation",
            "state": "Completed",
            "number": 71100732065,
            "amount": 1500,
            "vatAmount": 375,
            "description": "Test Cancellation",
            "payeeReference": "AB123"
        }
    }
}
Property Type Description
payment string The relative URL of the payment this cancellation transaction belongs to.
cancellation object The cancellation object, containing information about the cancellation transaction.
id string The relative URL of the cancellation transaction.
transaction object The object representation of the generic transaction resource, containing information about the current transaction.
id string The relative URL 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 integer The transaction number, useful when there’s need to reference the transaction in human communication. Not usable for programmatic identification of the transaction, where id should be used instead.
amount integer The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. 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 A human readable description of maximum 40 characters of the transaction.
payeeReference string(30) A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent to the acquirer and the payeeReference must be in the format of A-Za-z0-9 and string(30). If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12). All characters must be digits. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.

Top of page

Cancel Sequence Diagram v3.0

Cancel can only be done on an authorized transaction. As a cancellation does not have an amount associated with it, it will release the entire reserved amount. If your intention is to make detailed handling, such as only capturing a partial amount of the transaction, you must start with the capture of the desired amount before performing a cancel for the remaining reserved funds.

sequenceDiagram
    participant SwedbankPay as Swedbank Pay


    Merchant->>SwedbankPay: POST <  cancellation>
    activate Merchant
    activate SwedbankPay
    SwedbankPay-->>Merchant: transaction resource
    deactivate SwedbankPay
    deactivate Merchant

Top of page

Reversal v3.0

This transaction is used when a Capture or Sale payment needs to be reversed.

Please note that you have a maximum of 5 consecutive failed attempts at a reversal. The payment will be locked after this, and you need to contact us for another attempt.

If we want to reverse a previously captured amount, we need to perform reversal against the accompanying href returned in the operations list.

Top of page

Reversal Request v3.0

Request 



1
2
3
4



POST /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/reversals HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.0     // Version optional, can be set in `productName`





1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41



{
    "transaction": {
        "description": "Reversal of captured transaction",
        "amount": 1500,
        "vatAmount": 375,
        "payeeReference": "ABC123",
        "receiptReference": "ABC122",
        "orderItems": [
            {
                "reference": "P1",
                "name": "Product1",
                "type": "PRODUCT",
                "class": "ProductGroup1",
                "itemUrl": "https://example.com/products/123",
                "imageUrl": "https://example.com/product123.jpg",
                "description": "Product 1 description",
                "discountDescription": "Volume discount",
                "quantity": 4,
                "quantityUnit": "pcs",
                "unitPrice": 300,
                "discountPrice": 200,
                "vatPercent": 2500,
                "amount": 1000,
                "vatAmount": 250
            },
            {
                "reference": "P2",
                "name": "Product2",
                "type": "PRODUCT",
                "class": "ProductGroup1",
                "description": "Product 2 description",
                "quantity": 1,
                "quantityUnit": "pcs",
                "unitPrice": 500,
                "vatPercent": 2500,
                "amount": 500,
                "vatAmount": 125
            }
        ]
    }
}
Required Field Type Description
check transaction object The transaction object.
check amount integer The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The amount displayed is the final amount the payer paid for their order, including any payment method specific discounts or fees.
check vatAmount integer The payment’s VAT (Value Added Tax) amount, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The vatAmount entered will not affect the amount shown on the payment page, which only shows the total amount. This field is used to specify how much of the total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.
check payeeReference string(30) A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent to the acquirer and the payeeReference must be in the format of A-Za-z0-9 and string(30). If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12). All characters must be digits. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.
  receiptReference string(30) A unique reference to the transaction, provided by the merchant. Can be used as an invoice or receipt number as a supplement to payeeReference.
check description string Textual description of why the transaction is reversed.
check orderItems array 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.
check reference string A reference that identifies the order item.
check name string The name of the order item.
check type enum PRODUCT, SERVICE, SHIPPING_FEE, PAYMENT_FEE, DISCOUNT, VALUE_CODE or OTHER. The type of the order item.
check class string The classification of the order item. Can be used for assigning the order item to a specific product category, such as MobilePhone. Note that class cannot contain spaces and must follow the regex pattern [\w-]*. Swedbank Pay may use this field for statistics.
  itemUrl string The URL to a page that can display the purchased item, product or similar.
  imageUrl string The URL to an image of the order item.
  description string The human readable description of the order item.
  discountDescription string The human readable description of the possible discount.
check quantity number The 4 decimal precision quantity of order items being purchased.
check quantityUnit string The unit of the quantity, such as pcs, grams, or similar. This is used for your own book keeping.
check unitPrice integer The price per unit of order item, including VAT.
  discountPrice integer If the order item is purchased at a discounted price. This field should contain that price, including VAT.
check vatPercent integer The percent value of the VAT multiplied by 100, so 25% becomes 2500.
check amount integer The total amount including VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 SEK and 5000 equals 50.00 SEK.
check vatAmount integer The total amount of VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 SEK and 5000 equals 50.00 SEK.

Top of page

Reversal Response v3.0

If the reversal request succeeds, the response should be similar to the example below:

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



{
    "payment": "/psp/creditcard/payments/09ccd29a-7c4f-4752-9396-12100cbfecce",
    "reversal": {
        "id": "/psp/creditcard/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/reversals/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "transaction": {
            "id": "/psp/pcreditcard/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "created": "2022-01-26T14:00:03.4725904Z",
            "updated": "2022-01-26T14:00:04.3851302Z",
            "type": "Reversal",
            "state": "Completed",
            "number": 71100730898,
            "amount": 1500,
            "vatAmount": 375,
            "description": "Reversing the capture amount",
            "payeeReference": "ABC123",
            "receiptReference": "ABC122"
            "isOperational": false,
            "reconciliationNumber": 738180,
            "operations": []
        }
    }
}
Property Type Description
payment string The relative URL of the payment this reversal transaction belongs to.
reversals object The reversal object, containing information about the reversal transaction.
id string The relative URL of the reversal transaction.
transaction object The object representation of the generic transaction resource, containing information about the current transaction.
id string The relative URL of the current transaction resource.
created string The ISO-8601 date and time of when the transaction was created.
updated string The ISO-8601 date and time of when the transaction was updated.
type string Indicates the transaction type.
state string Indicates the state of the transaction, usually initialized, completed or failed. If a partial has been done and further transactions are possible, the state will be awaitingActivity.
number integer The transaction number, useful when there’s need to reference the transaction in human communication. Not usable for programmatic identification of the transaction, where id should be used instead.
amount integer The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. 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 A human readable description of maximum 40 characters of the transaction.
payeeReference string(30) A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent to the acquirer and the payeeReference must be in the format of A-Za-z0-9 and string(30). If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12). All characters must be digits. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.
receiptReference string(30) A unique reference to the transaction, provided by the merchant. Can be used as an invoice or receipt number as a supplement to payeeReference.
isOperational boolean true if the transaction is operational; otherwise false .
reconciliationNumber string The number of the reconciliation batch file where the transaction can be found.
operations array The array of operations that are possible to perform on the payment order in its current state.

Done With The Basics

You have reached the final step of the basic payment implementation and should be able to validate that everything works as intended, or maybe it’s time for acceptance tests?

Some of our payment methods require a few additional steps before they can be activated and become available in your payment UI. Read more about them and what you need to do by clicking the cards below.

There are other features and capabilities you can add to tailor the payment requests in order to meet your business needs. See what else we can offer by clicking Additional Request Options.

Apple Pay

How to activate Apple Pay webflow or in-app
Click to Pay

Additional signup needed for Click to Pay
Google Pay™

Additional signup needed for Google Pay™
Trustly

How to enable Trustly Express

Top of page