Invoice

One-Click Payments

schedule 5 min read

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 or invoice payments pages - which means that the payer don’t need to enter these details for every purchase.

Introduction

For card and invoice 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",
    }
}

Finding The paymentToken Value

When the initial purchase is successful, a paymentToken is linked to the payment. You can return the value by sending a GET request towards the payment resource (expanding either the authorizations or verifications sub-resource), after the payer successfully has completed the purchase. The two examples are provided below.

Request Towards Authorizations Resource

1
2
3
GET  /psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/verifications HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>

Request Towards Verifications Resource

1
2
GET /psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations HTTP/1.1
Authorization: Bearer <AccessToken>

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 to your system, you can use your payerReference to initiate one-click payments. Either by using the payerReference and setting generatePaymentToken to true, or by using payerReference and including a paymentToken in the paymentToken field. The payerReference is not generated by Swedbank Pay, but a reference set by you to identify your customer and their returning payments. An example could be to use internal customer numbers.

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.

You can add the field noCvc set to true in the creditcard object, containing card specific feature fields. This disables the CVC field.

One-Click Request Displaying All Cards

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
POST /psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1 HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "payment": {
        "operation": "Purchase",
        "intent": "Authorization",
        "generatepaymentToken": "true"
    },
    "payer": {
        "payerReference": "AB1234",
    },
    "creditCard": {
        "noCvc": true
    }
}

One-Click Request Displaying A Specific Card

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
POST /psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1 HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "payment": {
        "operation": "Purchase",
        "intent": "Authorization",
        "paymentToken": "5a17c24e-d459-4567-bbad-aa0f17a76119"
    },
    "payer": {
        "payerReference": "AB1234",
    },
    "creditCard": {
        "noCvc": true
    }
}
Required Field Type Description
check payment object The payment object.
check └➔ operation string Determines the initial operation, that defines the type card payment created.

Purchase. Used to charge a card. It is followed up by a capture or cancel operation.

Recur.Used to charge a card on a recurring basis. Is followed up by a capture or cancel operation (if not Autocapture is used, that is).

Payout. Used to deposit funds directly to credit card. No more requests are necessary from the merchant side.

Verify. Used when authorizing a card withouth reserveing any funds. It is followed up by a verification transaction.
check └➔ intent string The intent of the payment identifies how and when the charge will be effectuated. This determine the type transactions used during the payment process.

Authorization. Reserves the amount, and is followed by a cancellation or capture of funds.

AutoCapture. A one phase-option that enable capture of funds automatically after authorization.
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.
  └➔ creditCard object An object that holds different scenarios for card payments.
  └─➔ noCvc boolean true if the CVC field should be disabled for this payment in the case a stored card is used; otherwise false per default. To use this feature it has to be enabled on the contract with Swedbank Pay.
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

{
  "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
24
25
26
27
28
29
30
31
32
HTTP/1.1 200 OK
Content-Type: application/json

{
  "payerOwnedTokens": {
        "id": "/psp/paymentorders/payerownedtokens/{payerReference}",
        "payerReference": "{payerReference}",
        "tokens": [
            {
                "token": "{paymentToken}",
                "tokenType": "Payment",
                "instrument": "Invoice-payexfinancingno",
                "instrumentDisplayName": "260267*****",
                "instrumentParameters": {
                    "email": "hei@hei.no",
                    "msisdn": "+4798765432",
                    "zipCode": "1642"
                }
            },
            {
                "token": "{paymentToken}",
                "tokenType": "Unscheduled",
                "instrument": "CreditCard",
                "instrumentDisplayName": "492500******0004",
                "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 a payment token and is connected to a card.

Delete Single Token Request

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
PATCH /psp/creditcard/payments/instrumentData/5a17c24e-d459-4567-bbad-aa0f17a76119 HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

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

}
}

Delete Single Token Response

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
HTTP/1.1 200 OK
Content-Type: application/json

{
  "instrumentData": {
    "id": "/psp/creditcard/payments/instrumentdata/12345678-1234-1234-1234-123456789000",
    "paymentToken": "12345678-1234-1234-1234-123456789000",
    "payeeId": "61c65499-de5c-454e-bf4c-043f22538d49",
    "isDeleted": true,
    "isPayeeToken": false,
    "cardBrand": "Visa",
    "maskedPan": "123456xxxxxx1111",
    "expiryDate": "MM/YYYY",
    "tokenType" : "PaymentToken"
  }
}