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:

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": "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 e-mail is mandatory for any token creation.

The call works like Charge/CreatePayment. A transaction of type VERIFY 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.

Pour plus d'informations, rendez-vous ici: undefined.

Using a token: zero-click payment without form display

You can create a transaction from an alias without user interaction (no CVV request or 3D Secure authentication). The call will be server to server and will return a transaction (no notification of end of payment in this case).

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": "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"
}

Issue a SEPA Direct Debit request

The Charge/CreatePayment Web Service can be used to issue a direct debit request, provided that the debtor has signed a recurring direct debit mandate.

See the SEPA Direct Debit integration documentation for more information on signing mandates and implementing SDD recurring payments.

To issue a direct debit request, call the Charge/CreatePayment Web Service in SILENT mode, passing the UMR to be debited in the paymentMethodToken attribute.

SILENT mode is activated by setting the formAction attribute to "SILENT". Any other value will cause the request to be rejected.

Based on the constraints of the various constraints, the merchant knows when to issue a direct debit request. Therefore the merchant has the control of the date of the fund transfer. The amount of direct debits can vary from one instalment to another.

If the transaction is successful, the Web Service returns a Payment object. The background transfer date is returned in the transaction.transactionDetails.cardDetails.expectedCaptureDate attribute.

Example of a request:

{
  "amount":"3990",
  "currency":"EUR",
  "formAction":"SILENT",
  "paymentMethodToken":"0d75bd5f1fef4e779a4154e65abb39ca",
  "orderId":"myOrderId-605811",
  "customer":{
    "email":"sample@example.com",
    "reference":"12345678"
  }
}