Creating and using a token

Once-click payment is also called payment by token, or payment by identifier. You will also encounter the term payment token.

The payment by token allows merchant websites to offer their clients 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).

Buyer reference and token

There are 2 types of identifiers:

  • The Buyer reference (Buyer account). It is generated by the merchant website and refers to the buyer reference. The buyer is free to choose how to manage his or her account (for example, to sign in with an e-mail address and a password). The information on the Buyer account is stored by the merchant website.
  • The token (payment method ID). It refers to the payment method (credit card, bank account, etc.) and to all the information related to it and its holder. It is associated with a Buyer reference (or Buyer account). The banking details are stored and secured by the payment gateway that has received PCI-DSS agreement required for storing card numbers. Only the token is transferred during the exchange.

Note: the payment gateway does not verify whether the Buyer reference (or Buyer account) is unique. The token is unique and can be generated either by the merchant website or by the gateway.

Payments by token

The token allows to:

  • The fast and secure 1-click payment. The buyer no longer has to fill in bank details during subsequent payments. In this case, a simple confirmation step is presented with a summary of the transaction. If the payment amount is a bank card, the CVV code may be required at this stage if the card has one.
  • 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

In order to create a Token, one must define the formAction parameter. You must take two parameters:

formAction Description
ASK_REGISTER_PAY Add a checkbox to the payment form save my card
REGISTER_PAY The token will be created automatically

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": "69876357",
        "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 call works as Charge/CreatePayment. A transaction for zero euros will be created. The token will be returned in transactions[0].paymentMethodToken.

Using a token in the REST API

If you have previously recorded a payment method (card token), you can directly record a payment using payment by token. Thanks to this method, the buyer does not need to enter their card details once again.

To record a card, go to:

A card token looks like this:

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 directly returns a transaction as follows:

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