Documentation

1Introduction

The token is a reference to stored information in the platform. As this information may be sensitive or not structured we offer you an easy way to store this information in our platform by creating a token with a reference. For using the information with the payment for example with a charge flow or a transaction you can use this token and do not need to ask the customer for the information again.

The main use case for token is to store critical credit card information as they may only be stored inside PCI certified environments. But there are various other occasions where the usage of tokens can be useful. You can create a token for every connector that supports tokenization.

Example

A client already ordered online in your store using SEPA Direct Debit as payment method. You can store this information with a token for further purchase. Imagine he calls after 4 months and wants to reorder some products. You can now create a customer not present transaction by using the token reference without asking for the information again.

2Token Operations

All token operations can be done via the Token Service. Created token can be viewed in the back office under Space > Payment > Token

2.1What Payment Methods Do Support Tokens?

Not all payment methods and connector configurations do support the token feature. If you want to check if the payment methods does support it you find more information in our payment method reference. You can do that by opening your processor on our connector list and click on the connector. This will open a screen that shows the features of the payment page.

iframe
Figure 1. The page above shows the feature page of the payment connector.

2.2Create a Token

If the recurrent payment is selected a Token is created after the first payment. In order to create a token you use the Token Service with the operation create.

You can set if the token should be enabled for one-click payment. When a token is enabled for one-click payments the buyer will be able to select the token within the iFrame or on the payment page to pay with the token. The usage of the token will reduce the number of steps the buyer has to go through. The buyer is recognized by the customer ID on the transaction. That means the buyer will be presented with the previously used tokens when we have a token that has the same customer ID as the transaction. Additionally the payment method has to be configured to allow the one-click payments.

The request below creates a new token for a the test-customer. The payment reference will now automatically be stored in the Token Version.

Request

{
    "customerEmailAddress": "[email protected]",
    "enabledForOneClickPayment": true,
    "externalId": "1",
    "state": "ACTIVE",
    "tokenReference": "test-customer"
}

Response

The request below creates a transaction using the created token.

{
	"createdOn": "2017-12-07T14:53:20.285Z",
	"customerEmailAddress": "[email protected]",
	"customerId": null,
	"deletedOn": null,
	"enabledForOneClickPayment": true,
	"externalId": "1",
	"id": 1572,
	"language": null,
	"linkedSpaceId": 396,
	"plannedPurgeDate": null,
	"state": "ACTIVE",
	"timeZone": "Europe/Zurich",
	"timeZoneRaw": null,
	"tokenReference": "test-customer",
	"version": 0
}

2.3Using a Token

You can use the token to create a transaction. In order to do this just provide the id of the token in the Transaction Create Operation. The token can now be used in the following ways:

  1. You can show the token using the iframe authorization which will then let your customer choose the token to process the transaction.

  2. You can use the token using the payment page authorization. This will directly charge the customer and send him to the successURL or failedURL depending if the token could be charged.

  3. You can apply a Charge Flow on the transaction that uses a token. This will result in a direct charge or the Charge Flow Levels will be triggered in case the token can not be charged.

Request

The request below creates a transaction using the created token.

{
    "billingAddress": {
        "city": "Zurich",
        "country": "Switzerland",
        "familyName": "Test",
        "givenName": "Customer",
        "street": "Teststreet 4"
    },
    "currency": "chf",
    "lineItems": [
        {
            "amountIncludingTax": "15",
            "name": "Test",
            "quantity": "1",
            "type": "PRODUCT",
            "uniqueId": "12354"
        }
    ],
    "token": {
        "id": 1572
    }
}

3One Click Checkout

One click checkout increases your conversion because the payment information of your customer can be securely stored for further purchases so that the next time your customer is able to pay direclty using the token. This feature is available on the Iframe or Payment Page Integration for all payment method that support token (see above).

3.1Requirements

In order for one-click checkout to work you have to make sure that the following requirements are fulfilled:

In case these requirements are fulfilled the application will automatically initialize a token and store the payment information securely with your processor. This will work on the payment page integration and on the iframe integration.

3.2Activate the One-Click-Payment Mode

Make sure that for every payment method you want to activate one-click you have to enable the one-click payment mode. You have the choice between 3 options:

  1. Disable (default): In this case no token will be created

  2. Force Storage: In this case the application will alway try to create a token.

  3. Allow Storage: In this case the client will be asked if he wants to store the token. He has also the option to manage the stored tokens.

iframe
Figure 2. Payment page with the option to store the information and create a token for later use.

3.3Use the Token

As soon as a customer ID is provided and the one-click mode is activated and there is a token on file the buyer will be presented with a token to pay or he has the option to use another payment method.

In case you want to charge the token directly you can provide the tokenId directly in the Transaction Server Create Operation in this case the token will be charged directly.

iframe
Figure 3. The payment page with the option to use or mangae the token.