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.

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.

Get Request 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.x/2.0      // Version optional for 3.0 and 2.0





1
2
3
4
5
6



{
    "generatePaymentToken": true,
    "payer": {
    "payerReference": "AB1234",
    }
}

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

GET Request 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.x/2.0      // Version optional for 3.0 and 2.0





1
2
3
4
5
6



{
    "generatePaymentToken": true,
    "payer": {
    "payerReference": "AB1234",
    }
}

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

One-Click Request Displaying All Cards 



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



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

One-Click Request Displaying A Specific Card

One-Click Request Displaying A Specific Card 



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



{
    "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.

This is a feature intended for instrument mode and or custom menus.

If you have built your own interface to display previously stored details and generate transactions using them (“One-Click Request Displaying A Specific Card”), you will also have the need to include an option for them to store new details. This can be performed using either a Purchase or Verify operation.

For Purchase operations aiming to store new details simultaneously, you will need to utilize the disableStoredPaymentDetails parameter. This is because the payer has already made the decision not to use any stored details in your interface. By including this parameter, you effectively eliminate the need for confirmation in our UI, due to how the combination of generatePaymentToken and payerReference works in our API.

By employing this parameter, you as the Merchant will assume the responsibility of colllecting the payer’s consent for purpose of storing their details. If you do not want this responsibility and would like for us to help you out, you can combine disableStoredPaymentDetails along with enablePaymentDetailsConsentCheckbox and flag them both as true. That will enable our handler for collecting consent from the payer for you inside our Swedbank Pay UI. When the choice has been made and transaction is completed, we will relay that information to you. We will do this by setting the flag paymentTokenGenerated in the subsequent GET call towards the PaymentOrder to either true or false.

Verify operations do not require the use of these additional parameters, as they do not display any previously stored details based on your supplied reference, thereby avoiding redundancy. Including them in a Verify will result in a validation error.

generatePaymentToken field 



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



{
 "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.

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



PATCH /psp/paymentorders/payerownedtokens/<payerReference> 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



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

Delete Payment Token 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



{
  "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



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





1
2
3
4



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

Delete Single Token Response For Checkout Integrations

Response 



1
2
3



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





1
2
3
4
5
6
7
8
9
10



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