Card

Recur

schedule 7 min read

Setting up subscriptions and recurring payments.

Edit "Recur" on GitHub

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

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

There are two ways to initiate recurring payments procedures, depending on if you want to make an initial charge or not:

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

  • Initiate a recurring payment flow without charging the credit card. This is done by creating a “Verify 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
  • When posting a Verify payment, a payment token will be generated automatically.

Creating a Payment

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

  • You need to POST a Verify payment, that will automatically generate a recurrence token (for later recurring use).

Retrieve 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 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 instrument details and recurrence token from the initial payment.

Request

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

{
    "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
        }
    }
}
Required Field Type Description
check payment object The payment object.
check operation object Recur.
check └➔ recurrenceToken string The created recurrenceToken, if operation: Verify, operation: Recur or generateRecurrenceToken: true was used.
check └➔ currency string The currency of the payment order.
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.
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 └➔ description string A 40 character length textual description of the purchase.
check └─➔ userAgent string The User-Agent string of the payer’s web browser.
check └─➔ 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.
check └─➔ urls string The URL to the urls resource where all URLs related to the payment order can be retrieved.
check └─➔ callbackUrl string The URL that Swedbank Pay will perform an HTTP POST against every time a transaction is created on the payment. See callback for details.
check └➔ payeeInfo string The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details.
check └─➔ payeeId string This is the unique id that identifies this payee (like merchant) set by Swedbank Pay.
check └➔ payeeReference string(30) A unique reference from the merchant system. It is set per operation to ensure an exactly-once delivery of a transactional operation. See payeeReference for details. 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 used to supplement payeeReference as an additional receipt number.
check └─➔ payeeName string The payee name (like merchant name) that will be displayed when redirected to Swedbank Pay.
check └─➔ productCategory string 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.
check └─➔ orderReference String(50) The order reference should reflect the order reference found in the merchant’s systems.
check └─➔ subsite String(40) The subsite field can be used to perform split settlement on the payment. The subsites must be resolved with Swedbank Pay reconciliation before being used.
  └➔ 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 A unique reference from the merchant system. It is set per operation to ensure an exactly-once delivery of a transactional operation. See payeeReference for details. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.
info

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.

Autorization (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 Verify payment lets you post verifications to confirm the validity of card information, without reserving or charging any amount. This option is often used to initiate a recurring payment flow where you do not want to charge the payer right away.

info

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

{
    "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-canceled",
            "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
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
HTTP/1.1 200 OK
Content-Type: application/json

{
    "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": "PostmanRuntime/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"
        }
    ]
}