Online Payments

Recur

Setting up subscriptions and recurring payments. Card

Recur

A recur payment is a payment which uses a recurrenceToken generated through a previous payment in order to charge the same card or account at a later time.

As the name implies, these payments are used for transactions which happen on a recurring basis. Common use cases could be subscriptions for magazines, newspapers or streaming services.

Identify the recurring model and token type based on your needs. We support both dynamic and static prices and intervals. Use the RecurrenceToken flow for recurring payments with a constant price and interval, and the UnscheduledToken flow for variable services or goods. We highly recommend using the unscheduled option, as it gives you flexibility regarding changes in amount and interval.

Please note that you need to do a capture after sending the request. We have added a capture section at the end of this page for that reason.

Generating The Token

First, you need an initial transaction where the recurrenceToken is generated and connected. You do that by adding the field generateRecurrenceToken in the PaymentOrder request and set the value to true. The payer must complete the purchase to activate the token.

(Read more about deleting the recurrence token here.)

Initial Recur Request

The initial request should look like this:

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.x/2.0      // Version optional for 3.0 and 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
100
101
102
103



{
    "paymentorder": {
        "operation": "Purchase",
        "currency": "SEK",
        "amount": 1500,
        "vatAmount": 375,
        "description": "Test Purchase",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "generateRecurrenceToken": true, 
        "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" ], 
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-cancelled",
            "callbackUrl": "https://api.example.com/payment-callback",
            "termsOfServiceUrl": "https://example.com/termsandconditions.pdf"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "AB832",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-123456",
            "subsite": "MySubsite", 
            "siteId": "MySiteId", 
        },
        "payer": {
            "digitalProducts": false,
            "firstName": "Leia",
            "lastName": "Ahlström",
            "email": "leia@swedbankpay.com",
            "msisdn": "+46787654321",
            "payerReference": "AB1234",
            "shippingAddress": {
                "firstName": "firstname/companyname",
                "lastName": "lastname",
                "email": "karl.anderssson@mail.se",
                "msisdn": "+46759123456",
                "streetAddress": "string",
                "coAddress": "string",
                "city": "Solna",
                "zipCode": "17674",
                "countryCode": "SE"
            },
            "billingAddress": {
                "firstName": "firstname/companyname",
                "lastName": "lastname",
                "email": "karl.anderssson@mail.se",
                "msisdn": "+46759123456",
                "streetAddress": "string",
                "coAddress": "string",
                "city": "Solna",
                "zipCode": "17674",
                "countryCode": "SE"
            },
            "accountInfo": {
                "accountAgeIndicator": "04",
                "accountChangeIndicator": "04",
                "accountPwdChangeIndicator": "01",
                "shippingAddressUsageIndicator": "01",
                "shippingNameIndicator": "01",
                "suspiciousAccountActivity": "01",
            }
        },
        "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": 5,
                "quantityUnit": "pcs",
                "unitPrice": 300,
                "discountPrice": 0,
                "vatPercent": 2500,
                "amount": 1500,
                "vatAmount": 375
            }
        ],
        "riskIndicator": {
            "deliveryEmailAddress": "olivia.nyhuus@swedbankpay.com",
            "deliveryTimeFrameIndicator": "01",
            "preOrderDate": "19801231",
            "preOrderPurchaseIndicator": "01",
            "shipIndicator": "01",
            "giftCardPurchase": false,
            "reOrderPurchaseIndicator": "01",
            "pickUpAddress": {
                "name": "Olivia Nyhus",
                "streetAddress": "Saltnestoppen 43",
                "coAddress": "",
                "city": "Saltnes",
                "zipCode": "1642",
                "countryCode": "NO"
            }
        }
    }
}
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](/checkout-v3/features/payment-operations/abort/) [Verify](/checkout-v3/features/optional/verify), [UnscheduledPurchase](/checkout-v3/features/optional/unscheduled), [Recur](/checkout-v3/features/optional/recur) and [Payout](/checkout-v3/features/optional/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 check
The description of the payment order.
generateRecurrenceToken boolean
true or false. Set to true if you want to generate an recurrenceToken for future recurring purchases.
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 URLs valid for embedding of Swedbank Pay Seamless Views.
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`](/checkout-v3/technical-reference/complete-url) for details.
cancelUrl string
The URL to redirect the payer to if the payment is cancelled, either by the payer or by the merchant trough an abort request of the payment or paymentorder.
callbackUrl string check
The URL that Swedbank Pay will perform an HTTP `POST` against every time a transaction is created on the payment order. See [callback](/checkout-v3/features/payment-operations/callback) for details. For recurring transactions, the callback will only be sent for Trustly transactions, not card.
payeeInfo object check
The `payeeInfo` object, containing information about the payee (the recipient of the money). See [`payeeInfo`](/checkout-v3/technical-reference/payee-info) for details.
payeeId string check
The ID of the payee, usually the merchant ID.
payeeReference string(30) 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.
productCategory string(50)
A product category or number sent in from the payee/merchant. This is not validated by Swedbank Pay, but will be passed through the payment process and may be used in the settlement process.
orderReference string(50)
The order reference should reflect the order reference found in the merchant's systems.
subsite string(40)
The `subsite` field can be used to perform a split settlement on the payment. The different `subsite` values must be resolved with Swedbank Pay reconciliation before being used. If you send in an unknown `subsite` value, it will be ignored and the payment will be settled using the merchant's default settlement account. Must be in the format of `A-Za-z0-9`.
siteId string(15)
`siteId` is used for split settlement transactions when you, as a merchant, need to specify towards AMEX which sub-merchant the transaction belongs to. Must be in the format of `A-Za-z0-9`.
payer object
The payer object containing information about the payer relevant for the payment order.
email string
The e-mail address of the payer. Will be used to prefill the Checkin as well as on the payer's profile, if not already set. Increases the chance for frictionless 3-D Secure 2 flow .
msisdn string
The mobile phone number of the Payer. Will be prefilled on Checkin page and used on the payer's profile, if not already set. The mobile number must have a country code prefix and be 8 to 15 digits in length. The field is related to 3-D Secure 2 .
workPhoneNumber string
The work phone number of the payer. Optional (increased chance for frictionless flow if set) and is related to 3-D Secure 2 .
homePhoneNumber string
The home phone number of the payer. Optional (increased chance for frictionless flow if set) and is related to 3-D Secure 2 .
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 string check
PRODUCT, SERVICE, SHIPPING_FEE, PAYMENT_FEE DISCOUNT, VALUE_CODE or OTHER. The type of the order item. PAYMENT_FEE is the amount you are charged with when you are paying with invoice. The amount can be defined in the amount field below.
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, product or similar.
imageUrl string
The URL to an image of the order item.
description string
A textual [description](/checkout-v3/technical-reference/description) of the purchase. Maximum length is 40 characters.
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. This is used for your own book keeping.
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.
riskIndicator array
This optional object consist of information that helps verifying the payer. Providing these fields decreases the likelihood of having to prompt for 3-D Secure 2.0 authentication of the payer when they are authenticating the purchase.
deliveryEmailAdress string
For electronic delivery, the email address to which the merchandise was delivered. Providing this field when appropriate decreases the likelihood of a 3-D Secure authentication for the payer.
deliveryTimeFrameIndicator string
Indicates the merchandise delivery timeframe.
01 (Electronic Delivery)
02 (Same day shipping)
03 (Overnight shipping)
04 (Two-day or more shipping)
preOrderDate string
For a pre-ordered purchase. The expected date that the merchandise will be available. Format: YYYYMMDD
preOrderPurchaseIndicator string
Indicates whether the payer is placing an order for merchandise with a future availability or release date.
01 (Merchandise available)
02 (Future availability)
shipIndicator string
Indicates shipping method chosen for the transaction.
01 (Ship to cardholder's billing address)
02 (Ship to another verified address on file with merchant)
03 (Ship to address that is different than cardholder's billing address)
04 (Ship to Store / Pick-up at local store. Store address shall be populated in shipping address fields)
05 (Digital goods, includes online services, electronic giftcards and redemption codes)
06 (Travel and Event tickets, not shipped)
07 (Other, e.g. gaming, digital service)
giftCardPurchase bool
true if this is a purchase of a gift card.
reOrderPurchaseIndicator string
Indicates whether the cardholder is reordering previously purchased merchandise.
01 (First time ordered)
02 (Reordered).
pickUpAddress object
If shipIndicator set to 04, then prefill this with the payers pickUpAddress of the purchase to decrease the risk factor of the purchase.
name string
If shipIndicator set to 04, then prefill this with the payers name of the purchase to decrease the risk factor of the purchase.
streetAddress string
If shipIndicator set to 04, then prefill this with the payers streetAddress of the purchase to decrease the risk factor of the purchase. Maximum 50 characters long.
coAddress string
If shipIndicator set to 04, then prefill this with the payers coAddress of the purchase to decrease the risk factor of the purchase.
city string
If shipIndicator set to 04, then prefill this with the payers city of the purchase to decrease the risk factor of the purchase.
zipCode string
If shipIndicator set to 04, then prefill this with the payers zipCode of the purchase to decrease the risk factor of the purchase.
countryCode string
If shipIndicator set to 04, then prefill this with the payers countryCode of the purchase to decrease the risk factor of the purchase.

Initial Recur Response

Response 



1
2
3



HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.x/2.0
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



{
    "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",
        "amount": 1500,
        "vatAmount": 375,
        "description": "Test Purchase",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "language": "sv-SE",
        "availableInstruments": [
            "CreditCard", ],   
        "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": [  
        {
            "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](/checkout-v3/get-started/fundamental-principles#url-usage) to understand how this and other URLs should be used in your solution.
created string
The ISO-8601 date of when the payment order was created.
updated string
The ISO-8601 date of when the payment order was updated.
operation string
Purchase
status string
Indicates the payment order's current status. Initialized is returned when the payment is created and still ongoing. The request example above has this status. Paid is returned when the payer has completed the payment successfully. See the Paid response. Failed is returned when a payment has failed. You will find an error message in the Failed response. Cancelled is returned when an authorized amount has been fully cancelled. See the Cancelled response. It will contain fields from both the cancelled description and paid section. Aborted is returned when the merchant has aborted the payment, or if the payer cancelled the payment in the redirect integration (on the redirect page). See the Aborted response.
currency string
The currency of the payment order.
amount integer
The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: **`10000`** = `100.00` SEK, **`5000`** = `50.00` SEK. The amount displayed is the final amount the payer paid for their order, including any 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](/checkout-v3/technical-reference/description) of the purchase. Maximum length is 40 characters.
initiatingSystemUserAgent string
The [user agent](/checkout-v3/technical-reference/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`.
recurrenceToken string
The generated recurrence token if operation: recur or generaterecurrenceToken: true was used.
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.
payer id
The URL to the payer resource where information about the payer can be retrieved.
orderItems id
The URL to the orderItems resource where information about the order items 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.
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.

GET The Token

The token can be retrieved by performing a GET towards paid. It will be visible under tokens in the paid field.

Request 



1
2
3
4



GET /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/paid HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.x/2.0      // Version optional for 3.0 and 2.0

As an alternative, you can also retrieve it by using the expand option when you GET your payment. The GET request should look like the one below, with a ?$expand=paid after the paymentOrderId. The response should match the initial payment response, but with an expanded paid field.

Request 



1
2
3
4



GET /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/ HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.x/2.0      // Version optional for 3.0 and 2.0

Performing The Recurring Purchase

When you are ready to perform the recurring purchase, simply add the recurrenceToken field to the paymentOrder request and use the token as the value. Your request should look like the example below, and the response will match the paymentOrder response from the initial purchase.

After The Recurring Purchase

Please remember that the recur request will reserve the amount, but not charge it. You will (i.e. when you are ready to ship purchased physical products) have to perform a Capture request later on to complete the recurring purchase. You can also Cancel it if needed.

Recur Request

Request 



1
2
3
4



POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.x/2.0      // Version optional for 3.0 and 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



{
    "paymentorder": {
        "operation": "Recur",
        "recurrenceToken": "7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "currency": "NOK",
        "amount": 1500,
        "vatAmount": 0,
        "description": "Test Recurrence",
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",  
        "productName": "Checkout3", // Removed in 3.1, can be excluded in 3.0 if version is added in header 
        "urls": {
            "callbackUrl": "https://example.com/payment-callback"  // Callbacks will only be sent for Trustly
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b"
            "payeeReference": "CD1234",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-12456",
            "subsite": "MySubsite",  
            "siteId": "MySiteId", 
        },
        "payer": {
            "payerReference": "AB1234",
        },
        "orderItems": [
            {
                "reference": "P1",
                "name": "Product1",
                "type": "PRODUCT",
                "class": "ProductGroup1",
                "itemUrl": "https://example.com/products/123",
                "imageUrl": "https://example.com/product123.jpg",
                "description": "Product 1 description",
                "discountDescription": "Volume discount",
                "quantity": 4,
                "quantityUnit": "pcs",
                "unitPrice": 300,
                "discountPrice": 200,
                "vatPercent": 2500,
                "amount": 1000,
                "vatAmount": 250
            },
            {
                "reference": "I1",
                "name": "InvoiceFee",
                "type": "PAYMENT_FEE",
                "class": "Fees",
                "description": "Fee for paying with Invoice",
                "quantity": 1,
                "quantityUnit": "pcs",
                "unitPrice": 1900,
                "vatPercent": 0,
                "amount": 1900,
                "vatAmount": 0,
                "restrictedToInstruments": [
                    "Invoice-PayExFinancingSe"
                ]
            }
        ]
    }
}
Field
Type
Required
payment object check
The payment object.
operation object check
Recur.
recurrenceToken string check
The created recurrenceToken if operation: Recur or generateRecurrenceToken: true was used.
currency string check
The currency of the payment order.
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 check

A textual description of the purchase. Maximum length is 40 characters.

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 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 string check
The URL to the urls resource where all URLs related to the payment order can be retrieved.
callbackUrl string

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

For recurring transactions, the callback will only be sent for Trustly transactions, not card.
payeeInfo object check

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

payeeId string check
This is the unique id that identifies this payee (like merchant) set by Swedbank Pay.
payeeReference string(30) 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.

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.

payeeName string check
The payee name (like merchant name) that will be displayed when redirected to Swedbank Pay.
productCategory string(50) check
A product category or number sent in from the payee/merchant. This is not validated by Swedbank Pay, but will be passed through the payment process and may be used in the settlement process.
orderReference string(50) check
The order reference should reflect the order reference found in the merchant's systems.
subsite string(40) check

The subsite field can be used to perform a split settlement on the payment. The different subsite values must be resolved with Swedbank Pay reconciliation before being used. If you send in an unknown subsite value, it will be ignored and the payment will be settled using the merchant’s default settlement account. Must be in the format of A-Za-z0-9.

siteId string(15)

siteId is used for split settlement transactions when you, as a merchant, need to specify towards AMEX which sub-merchant the transaction belongs to. Must be in the format of A-Za-z0-9.

payer object
The payer object, containing information about the payer.
payerReference string

The reference to the payer from the merchant system, like e-mail address, mobile number, customer number etc. Mandatory if generateRecurrenceToken, RecurrenceToken, generatePaymentToken or paymentToken is true.

metadata object

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.

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 string check
PRODUCT, SERVICE, SHIPPING_FEE, PAYMENT_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, 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.
quantity integer 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. This is used for your own book keeping.
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.

restrictedToInstruments array
A list of the payment methods you wish to restrict the payment to. Currently Invoice only. Invoice supports the subtypes PayExFinancingNo, PayExFinancingSe and PayMonthlyInvoiceSe, separated by a dash, e.g.; Invoice-PayExFinancingNo. Default value is all supported payment methods. Use of this field requires an agreement with Swedbank Pay. You can restrict fees and/or discounts to certain payment methods by adding this field to the orderline you want to restrict. Use positive amounts to add fees and negative amounts to add discounts.

Capture

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:

Capture Request

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/2.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
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
            }
        ]
    }
}
Field
Type
Required
transaction object check
The transaction object.
description string check
The description of the capture transaction.
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.

payeeReference string(30) 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.

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.

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, PAYMENT_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, 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.
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. This is used for your own book keeping.
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 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.
vatAmount integer check
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.
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, PAYMENT_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 a product page
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 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.
vatAmount integer check
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.

Capture Response

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/2.0
api-supported-versions: 3.0/2.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"
        }
    }
}
Field
Type
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.

Capture Sequence Diagram 

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