Digital Payments

One-Click Payments

Prefilling the payment details using payment tokens.

Edit "One-Click Payments" on GitHub

One-Click Payments

One-Click Payments utilize a previously generated payment token to prefill payment details for credit card payments pages - which means that the payer don’t need to enter these details for every purchase.

Introduction

For card and Trustly payments, the payment flow and implementation varies from your default only being the use of a paymentToken. The details in this section describe explicitly the parameters that must be set to enable one-click purchases.

API Requests To Generate The Payment Token

When making the initial purchase request, you need to generate a paymentToken. You can do this by setting the generatePaymentToken field in the request’s payment object to true (see example below) when doing a card purchase, or setting the initial operation to Verify.

generatePaymentToken field



1
2
3
4
5
6



{
    "generatePaymentToken": true,
    "payer": {
    "payerReference": "AB1234",
    }
}
Required Field Type Description
  generatePaymentToken bool Determines if a payment token should be generated. Default value is false.
  payer object The payer object
  payerReference string A reference used to recognize the payer when no SSN is stored.

Use the same basic initial payment order request, and add the new field enablePaymentDetailsConsentCheckbox in the paymentOrder node. Set it to true to show the checkbox used to store payment details for card payments. Remember to also set disableStoredPaymentDetails to true.

This option will not work with Verify, and will result in a validation error if you try.

Payment Details Consent Checkbox



1
2
3
4
5
6



{
 "paymentorder": {
    "enablePaymentDetailsConsentCheckbox": true,
    "disableStoredPaymentDetails": true,
  }
}
Required Field Type Description
check paymentOrder object The payment order object.
  EnablePaymentDetailsConsentCheckbox bool Set to true or false. Used to determine if the checkbox used to save payment details is shown or not. Will only work if the parameter disableStoredPaymentDetails is set to true.
  disableStoredPaymentDetails bool Set to true or false. Must be set to true for enablePaymentDetailsConsentCheckbox to work.

Finding The paymentToken Value

When the initial purchase is successful, a paymentToken is linked to the payment. You can return the value by performing a GET request towards the payment resource with the payerReference included.

Request Towards The Payment Resource



1
2
3
4



GET /psp/paymentorders/payerownedtokens/5a17c24e-d459-4567-bbad-aa0f17a76119 HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.1/3.0/2.0      // Version optional for 3.0 and 2.0

You can also perform a GET request towards the id of a Payment Order and find the paymentToken in its linked paid resource.

Request Towards The Paid Resource



1
2
3
4



GET /psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/paid HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.1/3.0/2.0      // Version optional for 3.0 and 2.0

You need to store the paymentToken from the response in your system and keep track of the corresponding payerReference in your system.

Returning Purchases

When a known payer returns, you can display their details by initiating the transaction with the parameter paymentToken and its associated value. Please note that the value in payerReference needs to be identical to the value given when the token was generated. We highly recommend that you use a value that represents the customer in your system, so it’s easier to keep track. An example could be an alpha-numerical value like “ABC123”.

For card payments, using payerReference and generatePaymentToken: true will display all (max 3) cards connected to the payerReference. If you wish to display one specific card only, you can remove generatePaymentToken and add the field paymentToken in it’s place. This must be the paymentToken generated in the initial purchase.

One-Click Request Displaying All Cards

Request



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



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      // Version optional for 3.0 and 2.0

{
    "paymentorder": {
        "operation": "Purchase",
        "generatepaymentToken": "true"
    },
    "payer": {
        "payerReference": "AB1234",
    }
}

One-Click Request Displaying A Specific Card

Request



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



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      // Version optional for 3.0 and 2.0

{
    "paymentorder": {
        "operation": "Purchase",
        "paymentToken": "5a17c24e-d459-4567-bbad-aa0f17a76119"
    },
    "payer": {
        "payerReference": "AB1234",
    }
}
Required Field Type Description
check paymentOrder object The paymentorder object.
check operation string Determines the initial operation, defining the type of payment order created.
check paymentToken string The paymentToken value received in GET response towards the Payment Resource is the same paymentToken generated in the initial purchase request. The token allow you to use already stored card data to initiate one-click payments.
  generatePaymentToken bool Determines if a payment token should be generated. Default value is false.
  payer object The payer object containing information about the payer relevant for the payment order.
  payerReference string A reference used in the Enterprise and Payments Only implementations to recognize the payer when no SSN is stored.
info

When redirecting to Swedbank Pay the payment page will be prefilled with the payer’s card details. See example below.

How It Looks

One click payment page

Delete Payment Token

If you need to delete a paymentToken, you have two options. The first is by payerReference, which deletes all payment, recurrence and/or unscheduled tokens associated with the payer. The second is by paymentToken, which only deletes a specific token.

warning

Please note that this call does not erase the card number stored at Swedbank Pay. A card number is automatically deleted six months after a successful Delete payment token request. If you want card information removed at an earlier date, you need to contact ehandelsetup@swedbankpay.dk, verkkokauppa.setup@swedbankpay.fi, ehandelsetup@swedbankpay.no or ehandelsetup@swedbankpay.se; and supply them with the relevant transaction reference or payment token.

If you want to delete tokens by payerReference, the request and response should look like this:

Delete Payment Token Request

Request



1
2
3
4
5
6
7
8
9



PATCH /psp/paymentorders/payerownedtokens/<payerReference> HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.1/3.0/2.0      // Version optional for 3.0 and 2.0

{
  "state": "Deleted",
  "comment": "Comment stating why this is being deleted"
}

Delete Payment Token Response

Response



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



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

{
  "payerOwnedTokens": {
        "id": "/psp/paymentorders/payerownedtokens/{payerReference}",
        "payerReference": "{payerReference}",
        "tokens": [
            {
                "tokenType": "Payment",
                "token": "{paymentToken}",
                "instrument": "CreditCard",
                "instrumentDisplayName": "492500******0004",
                "correlationId": "e2f06785-805d-4605-bf40-426a725d313d",
                "instrumentParameters": {
                    "expiryDate": "12/2020",
                    "cardBrand": "Visa"
                }
            }
        ]
    }
}

Deleting Single Tokens

For single token deletions, the request and response should look like this. In this example, the token is connected to a card. For Trustly transactions, it will be a masked account number.

Delete Single Token Request For Checkout Integrations

Request



1
2
3
4
5
6
7
8
9



PATCH /psp/paymentorders/paymenttokens/5a17c24e-d459-4567-bbad-aa0f17a76119 HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.1/3.0/2.0 // Version optional for 3.0 and 2.0

{
  "state": "Deleted",
  "comment": "Comment stating why this is being deleted"
}

Delete Single Token Response For Checkout Integrations

Response



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



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

{
  "paymentToken": "",
    "instrument": "CreditCard",
    "instrumentDisplayName": "492500******0004",
    "correlationId": "e2f06785-805d-4605-bf40-426a725d313d",
    "instrumentParameters": {
        "expiryDate": "12/2022",
        "cardBrand": "Visa"
    }
}