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
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
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. |
Disable Store Details and Toggle Consent Checkbox
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.
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"
}
}