Card – Recur

Recurring Payments

A recurring payment enables you to charge a card without payer interaction. When an initial payment token is generated, subsequent payments are made through server-to-server requests.

Prerequisites

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.

Prior to making any server-to-server requests, you need to supply the payment method details and a payment token to Swedbank Pay by initial purchase.

Initiate a recurring payment flow and charge the credit card. This is done by creating a “Purchase Payment” and generating a recurrence token.

Generate RecurrenceToken

When posting a Purchase payment, you need to make sure that the field generateRecurrenceToken is set to true.

Field

1

"generateRecurrenceToken": true

Creating The Payment

You need to POST a Purchase payment / and generate a recurrence token (safekeep for later recurring use).

Retrieve The Recurrence Token

You can retrieve the recurrence token by doing a GET request against the payment. You need to store this recurrenceToken in your system and keep track of the corresponding payerReference.

Delete The Recurrence Token

You can delete a created recurrence token. Please see technical reference for details here.

Recurring Purchases

When you have a Recurrence token stored away. You can use the same token in a subsequent recurring payment POST. This will be a server-to-server affair, as we have both payment method details and recurrence token from the initial payment.

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

Recur Request

Request

1
2
3
4

POST /psp//payments HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

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

{
    "payment": {
        "operation": "Recur",
        "intent": "Authorization",
        "recurrenceToken": "7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "currency": "NOK",
        "amount": 1500,
        "vatAmount": 0,
        "description": "Test Recurrence",
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "urls": {
            "callbackUrl": "https://example.com/payment-callback"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "CD1234",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-12456",
            "subsite": "MySubsite"
        },
        "payer": {
            "payerReference": "AB1234",
        },
        "metadata": {
            "key1": "value1",
            "key2": 2,
            "key3": 3.1,
            "key4": false
        }
    }
}

payment object

The payment object

operation object

Recur.

intent string

The intent of the payment identifies how and when the charge will be effectuated. This determines the transactions types used during the payment process. Authorization. Reserves the amount, and is followed by a cancellation or capture of funds. AutoCapture is a one phase-option that enable capture of funds automatically after authorization.

recurrenceToken string

The created recurrenceToken, if operation: Verify, operation: Recur or generateRecurrenceToken: true was used.

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.

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.

userAgent string

The User-Agent string of the payer's web browser.

language string

sv-SE, nb-NO, da-DK, de-DE, ee-EE, en-US, es-ES, fr-FR, lv-LV, lt-LT, ru-RU or fi-FI.

urls string

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

payeeInfo object

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

payeeId string

This is the unique id that identifies this payee (like merchant) set by Swedbank Pay.

payeeReference string(50)

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(50). 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

The payee name (like merchant name) that will be displayed when redirected to Swedbank Pay.

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

payer string

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

Please note that this POSTrequest is made directly on the payment level, and will not create a payment order.

Options after a payment

You have the following options after a server-to-server Recur payment POST.

Authorization (intent)

Authorization (two-phase): If you want the credit card to reserve the amount, you will have to specify that the intent of the purchase is Authorization. The amount will be reserved but not charged. You will later (i.e. when you are ready to ship the purchased products) have to make a Capture or Cancel request.

Capture (intent)

AutoCapture (one-phase): If you want the credit card to be charged right away, you will have to specify that the intent of the purchase is AutoCapture. This is only allowed if the payer purchases digital products. The card will be charged and you don’t need to do any more financial operations to this purchase.

General

Defining CallbackURL: When implementing a scenario, it is optional to set a CallbackURL in the POST request. If callbackURL is set Swedbank Pay will send a postback request to this URL when the payer has fulfilled the payment.

Verify

A card verification lets you post verifications to confirm the validity of card information, without reserving or charging any amount. You can use it for generating paymentTokens, but do not use it when generating recurrenceTokens.

This is because banks are rejecting recurring transactions where the amount is higher than the initial transaction. If the initial transaction amount is e.g. 1000, your subsequent recurring transaction amounts can be up to 1000 too, but 1001 will most likely be rejected. Since Verify transaction amounts are always 0, this can cause issues for you in the future.

Please note that all boolean credit card attributes involving rejection of certain card types are optional and set on contract level.

Request

1
2
3
4

POST /psp/creditcard/payments HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

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

{
    "payment": {
        "operation": "Verify",
        "currency": "NOK",
        "description": "Test Verification",
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "generatePaymentToken": true,
        "generateRecurrenceToken": false,
        "urls": {
            "hostUrls": [ "https://example.com" ],
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-cancelled",
            "paymentUrl": "https://example.com/perform-payment",
            "logoUrl": "https://example.com/payment-logo.png",
            "termsOfServiceUrl": "https://example.com/payment-terms.html"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "CD1234",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-12456",
            "subsite": "MySubsite"
        },
        "payer": {
            "payerReference": "AB1234",
        }
    },
    "creditCard": {
        "rejectCreditCards": false,
        "rejectDebitCards": false,
        "rejectConsumerCards": false,
        "rejectCorporateCards": false
    }
}

Response

1
2

HTTP/1.1 200 OK
Content-Type: application/json

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

{
    "payment": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 1234567890,
        "created": "2016-09-14T13:21:29.3182115Z",
        "updated": "2016-09-14T13:21:57.6627579Z",
        "operation": "Verify",
        "state": "Ready",
        "currency": "NOK",
        "amount": 0,
        "description": "Test Verification",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "userAgent": "Mozilla/5.0",
        "language": "nb-NO",
        "transactions": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions" },
        "verifications": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/verifications" },
        "urls" : { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls" },
        "payeeInfo" : { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo" },
        "payers": {"id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers" },
        "settings": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/settings" }
    },
    "operations": [
        {
            "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "rel": "update-payment-abort",
            "method": "PATCH",
            "contentType": "application/json"
        },
        {
            "href": "https://ecom.externalintegration.payex.com/creditcard/payments/verification/5a17c24e-d459-4567-bbad-aa0f17a76119",
            "rel": "redirect-verification",
            "method": "GET",
            "contentType": "application/json"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/creditcard/core/scripts/client/px.creditcard.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119",
            "rel": "view-verification",
            "contentType": "application/javascript"
        },
        {
            "method": "POST",
            "href": "https://ecom.externalintegration.payex.com/psp/creditcard/confined/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/verifications",
            "rel": "direct-verification",
            "contentType": "application/json"
        }
    ]
}

Capture

The capture transaction is where you ensure that the funds are charged from the payer. This step usually takes place when the product has exchanged possession. You must first do a GET request on the payment to find the create-capture operation.

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

Create Capture Transaction

To create a capture transaction to withdraw money from the payer’s card, you need to perform the create-capture operation.

Capture Request

Request

1
2
3
4

POST /psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

1
2
3
4
5
6
7
8

{
    "transaction": {
        "amount": 1500,
        "vatAmount": 250,
        "description": "Test Capture",
        "payeeReference": "ABC123"
    }
}

transaction object

The object representation of the generic transaction resource, containing information about the current transaction.

amount integer

Amount is entered in the lowest monetary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.

vatAmount integer

Amount is entered in the lowest monetary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.

description string

A textual description of the capture 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(50)`. **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**.

Capture Response

Response

1
2

HTTP/1.1 200 OK
Content-Type: application/json

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

{
    "payment": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "capture": {
        "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "transaction": {
            "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "created": "2016-09-14T01:01:01.01Z",
            "updated": "2016-09-14T01:01:01.03Z",
            "type": "Capture",
            "state": "Completed",
            "number": 1234567890,
            "amount": 1500,
            "vatAmount": 250,
            "description": "Test Capture",
            "payeeReference": "ABC123",
            "isOperational": false,
            "operations": []
        }
    }
}

payment string

The relative URL of the payment this capture transaction belongs to.

capture object

The capture resource contains information about the capture transaction made against a card payment.

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

Amount is entered in the lowest monetary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.

vatAmount integer

If the amount given includes VAT, this may be displayed for the user in the payment page (redirect only). Set to 0 (zero) if this is not relevant.

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(50)`. **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**.

failedReason string

The human readable explanation of why the payment failed.

isOperational boolean

true if the transaction is operational; otherwise false.

operations array

The array of operations that are possible to perform on the transaction in its current state.

List Capture Transactions

The captures resource list the capture transactions (one or more) on a specific payment.

Request

1
2
3
4

GET /psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

The capture resource contains information about the capture transaction made against a creditcard payment. You can return a specific capture transaction by performing a GET request towards the specific transaction’s id.

Transaction List Response

Response

1
2

HTTP/1.1 200 OK
Content-Type: application/json

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

{
    "paymentorder": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "captures": { 
        "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment",
        "captureList": [{
            "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "transaction": {
                "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                "created": "2016-09-14T01:01:01.01Z",
                "updated": "2016-09-14T01:01:01.03Z",
                "type": "Capture",
                "state": "Completed",
                "number": 1234567890,
                "amount": 1000,
                "vatAmount": 250,
                "description": "Test transaction",
                "payeeReference": "AH123456",
                "isOperational": false,
                "operations": []
            }
        }]
    }
}

paymentOrder string

The relative URL and unique identifier of the payment resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.

reversals object

The current captures resource.

id string

The relative URL and unique identifier of the captures resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.

reversalList array

The capture transaction object described in the capture resource below.

id string

The relative URL and unique identifier of the transaction resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.

created string

The ISO-8601 date 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 capture 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.

vatAmount integer

description string

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

payeeReference string(30)

isOperational bool

true if the transaction is operational; otherwise false.

operations array

The array of operations that are possible to perform on the transaction in its current state.

Capture Sequence Diagram

Capture can only be done on an authorized transaction. It is possible to do a partial capture where you only capture a part of the authorized amount. You can do more captures on the same payment up to the total authorization amount later.

sequenceDiagram
  activate Merchant
  Merchant->>-SwedbankPay: POST [ captures]
  activate SwedbankPay
  SwedbankPay-->>-Merchant: transaction resource