Creating and using a token

One-click payment is also called payment by token. The term payment token is also used for a token.

The payment by token allows merchant websites to offer their Buyers the possibility to associate a payment method with a token in order to facilitate subsequent payments on the website (without having to re-enter the bank card number).

Payments by token

The token allows:

  • One-click payment: Buyers no longer have to enter their bank details for subsequent payments. In this case, a simple confirmation step is presented with a transaction summary. If the payment method is a credit card, the visual cryptogram may be required at this stage, if present.
  • Zero-click payment: This mode allows you to create a transaction from a token without user interaction. The transaction is created during a server-to-server call.
  • Payment by subscription: Each Buyer account is associated with a subscription and an amount, with a limited or unlimited duration.

Under certain conditions (see with the payment gateway contact), identifiers (tokens) can be shared by several legal entities. Identifiers shared by several legal entities must be unique and must imperatively be generated by the payment gateway.

Creating a token during payment collection

The formAction parameter allows to create a token. Use one of the two following values:

formAction Description
ASK_REGISTER_PAY Adds a checkbox to the payment form for recording the card.
REGISTER_PAY The token will be created automatically.

The e-mail is mandatory for any token creation.

In the call to the Charge/CreatePayment web service:

    {
        "amount": 990,
        "currency": "EUR",
        "formAction": "ASK_REGISTER_PAY",
        "orderId": "myOrderId-999999",
        "customer": {
            "email": "sample@example.com"
        }
    }
    /**
 * I initialize the PHP SDK
 */
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';

/** 
 * Initialize the SDK 
 * see keys.php
 */
$client = new Lyra\Client();

/**
 * I create a formToken
 */
$store = array(
  "amount" => 250, 
  "currency" => "EUR", 
  "formAction" => "ASK_REGISTER_PAY",
  "orderId" => uniqid("MyOrderId"),
  "customer" => array(
    "email" => "sample@example.com"
));

$response = $client->post("V4/Charge/CreatePayment", $store);

/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
    /* an error occurs, I throw an exception */
    display_error($response);
    $error = $response['answer'];
    throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage'] );
}

/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];

?>

At the end of the payment, the PaymentTransaction object will contain the payment method token in the paymentMethodToken property:

{
    "orderCycle": "CLOSED",
    "orderStatus": "PAID",
    "serverDate": "2018-10-02T16:38:13+00:00",
    "orderDetails": (...)
    "customer": (...)
    "transactions": [
    {
        "shopId": "73239078",
        "uuid": "7af034f2883240c2876f6c61c7eab8ea",
        "amount": 990,
        "currency": "EUR",
        "paymentMethodType": "CARD",
        "paymentMethodToken": "b6e51ba31f934ac5b25ccad2a52ccd56",
        (...)
        "_type": "V4/PaymentTransaction"
        }
    ],
    "_type": "V4/Payment"
}

Creating a token without collecting a payment

In some cases, you only wish to create a token without collecting the payment. To do this, you must use the Charge/CreateToken web service:

{
    "currency": "EUR",
    "orderId": "myOrderId-999999",
    "customer": {
        "email": "sample@example.com"
    }  
}
    /**
 * I initialize the PHP SDK
 */
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';

/** 
 * Initialize the SDK 
 * see keys.php
 */
$client = new Lyra\Client();

/**
 * I create a formToken
 */
$store = array(
  "orderId" => uniqid("MyOrderId"),
  "customer" => array(
    "email" => "sample@example.com",
));

$response = $client->post("V4/Charge/CreateToken", $store);

/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
    /* an error occurs, I throw an exception */
    display_error($response);
    $error = $response['answer'];
    throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage'] );
}

/* everything is fine, I extract the formToken */
$formToken = $response["answer"]["formToken"];

?>

The e-mail is mandatory for any token creation.

The call works as Charge/CreatePayment. A VERIFICATION type transaction will be created.

kr-answer will therefore contain a Payment type object and the token will be returned in transactions[0].paymentMethodToken.

Using a token: one-click payment with form display

If you have previously recorded a payment method (card token), you can create a payment by transmitting the token to be debited in the paymentMethodToken field when calling the Charge/CreatePayment web service. With this method, buyers do not need to re-enter their card information. A pre-filled form will be presented to the buyer, he/she will simply need to validate it.

If your shop is configured to request the CVV or 3D Secure authentication during payments by token, the form will adapt automatically.

To use it, all you need to do is send the previously created token using the Charge/CreatePayment Web Service.

Example:

    {
        "amount": 990,
        "currency": "EUR",
        "paymentMethodToken": "b6e51ba31f934ac5b25ccad2a52ccd56"
    }
    /**
 * I initialize the PHP SDK
 */
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/keys.php';
require_once __DIR__ . '/helpers.php';

/** 
 * Initialize the SDK 
 * see keys.php
 */
$client = new Lyra\Client();

/**
 * create a transaction with a payment method token
 */
$store = array(
  "amount" => 250, 
  "currency" => "EUR",
  "paymentMethodToken" => "b6e51ba31f934ac5b25ccad2a52ccd56"
);

/**
 * do the web-service call
 */
$response = $client->post("V4/Charge/CreatePayment", $store);

/* I check if there are some errors */
if ($response['status'] != 'SUCCESS') {
    /* an error occurs, I throw an exception */
    display_error($response);
    $error = $response['answer'];
    throw new Exception("error " . $error['errorCode'] . ": " . $error['errorMessage'] );
}

?>

Charge/CreatePayment returns a formToken. You must then generate your payment form using the JavaScript client, in the same way as a single payment.

For more information, go to: Embedded form: Rapid testing.

Using a token: zero-click payment without form display

This operating mode cannot be used in the following cases:

  • Your shop is configured to request CVV entry for payments by token,
  • Your shop is configured to request 3D Secure authentication for payments by token,
  • As soon as v2 3D Secure is enabled for your MID.

You can create a transaction from a token without user interaction. The call will be made between servers and return a transaction.

To do this, make a call to the Charge/CreatePayment web service by transmitting the token and setting formAction to SILENT.

Example:

    {
        "amount": 990,
        "currency": "EUR",
        "paymentMethodToken": "b6e51ba31f934ac5b25ccad2a52ccd56",
        "formAction": "SILENT"
    }

Charge/CreatePayment directly returns a transaction as follows:

{
    "shopId": "73239078",
    "orderCycle": "CLOSED",
    "orderStatus": "PAID",
    "serverDate": "2018-09-27T14:02:17+00:00",
    "orderDetails": (...)
    "customer": (...)
    },
    "transactions": [{
        "shopId": "73239078",
        "uuid": "5b158f084502428499b2d34ad074df05",
        "amount": 990,
        (...)
        "_type": "V4/PaymentTransaction"
    }],
    "_type": "V4/Payment"
}