Get Started

Recurring

Getting started with Swedbank Pay recurring services

Edit "Recurring" on GitHub

Supported Payment Instruments

Looking to get started with recurring services? They are currently supported in Digital Payments using these instruments:

  • Card payments

Step 1: Create a Payment Order

To initiate recurring services, create a payment order with Swedbank Pay. This can be done by making an initial purchase, storing user details along with the transaction, or performing a Verify operation for account verification. Verify is a zero-sum operation used solely for registering details for future use.

Step 2: Choose Recurring Model and Token

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.

From a technical standpoint, both flows work identically, with the differences lying in usage areas and limitations set for merchants and expectations from payers.

Purchase Example

Start with the basic payment order request and modify it by including the parameter generateUnscheduledToken or generateRecurrenceToken: true | false. Include only the token(s) you intend to use.

Payment Request 



1
2
3
4



POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.1/3.0/2.0





1
2
3
4
5
6
7
8
9
10
11
12
13
14



{
"paymentorder": {
"operation": "Purchase",
"currency": "SEK",
"amount": 1500,
"vatAmount": 375,
"description": "Test Purchase",
"userAgent": "Mozilla/5.0...",
"language": "sv-SE",
"productName": "Checkout3",
"generateUnscheduledToken": "true | false",
"generateRecurrenceToken": "true | false"
    }
}

Verify

The Verify request is identical to the Purchase request, with the only tweak being the value of the operation parameter (should be Verify). Exclude amount, vatAmount, and the orderItems object since no monetary value is associated with this action.

Verify Request 



1
2
3
4



POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.1/3.0/2.0





1
2
3
4
5
6
7
8
9
10
11
12



{
"paymentorder": {
"operation": "Verify",
"currency": "SEK",
"description": "Test Purchase",
"userAgent": "Mozilla/5.0...",
"language": "sv-SE",
"productName": "Checkout3",
"generateUnscheduledToken": "true | false",
"generateRecurrenceToken": "true | false"
    }
}

Post-Purchase / Post-Verify

After the payer completes their interaction, retrieve the token in the Paid node by performing a GET call towards the Paid URL.

Response 



1
2
3



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





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



{
    "paid": {
    "id": "/psp/paymentorders/08349122-aa53-40e8-dd36-08dbbb319d19/paid",
    "instrument": "CreditCard", // Instrument used
    "number": 40126707630, // Transaction number associated with the action
    "tokens":[
        {
          "type": "unscheduled",
          "token": "e9e61882-7655-4023-adb1-a46b52e786b4",
          "name": "522661******3406",
          "expiryDate": "12/2033"
        },
        {
          "type": "recurrence",
          "token": "812db58a-a10e-4a96-80f2-8247ce2bc8d9",
          "name": "522661******3406",
          "expiryDate": "12/2033"
        }
       // ... other details
    }
}

Charging Your Customer

Now that your customer has stored their details and you’ve retrieved their token, you are ready to start charging based on the agreed-upon details (price & interval). Modify the parameters in the Purchase/Verify request as follows:

  • Operation: Use either UnscheduledPurchase or Recur based on the stored token. Modify the parameter generateUnscheduledToken or generateRecurrenceToken into unscheduledToken or recurrenceToken: “”.

  • URL: CallbackUrl is mandatory and will send you an asynchronous POST to make sure the information is received. Information regarding the results will also be displayed in the direct response to your request.

  • The payerReference in the Payer node needs to be consistent with the one used to create the token details in Purchase/Verify.

Removal of Instrument Details

When conditions like error codes or payer requests to remove details are met, you’ll need to delete associated tokens. Here are two methods:

  • Deletion of all tokens:

Send a PATCH call to the base URL with the endpoint /psp/paymentorders/payerOwnedTokens/<payerReference>.

  • Deletion of a singular token:

Use the URL /psp/paymentorders/unscheduledTokens/<TokenValue>.

  • Both scenarios generate the same response.

Response 



1
2
3



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





1
2
3
4



{
"state": "Deleted",
"comment": "Comment on why the deletion is happening"
}

Common causes that triggers the need for deletion

  • Your customer requests their information to be removed.

  • The agreement with your customer has been terminated or expired.

  • Error codes pertaining to permanent causes, for example Card expired (54) or Card stolen (43).

Sources

If you would like to read more in depth about each specific instance, we have compiled relevant documentation below.