Criação e uso de token cartão (token)

O pagamento em um clique também é chamado de pagamento por token cartão ou pagamento por código de identificação. Poderá achar também o termo token de pagamento para mencionar um Token Cartão.

O pagamento por Token Cartão possibilita aos sites de e-commerce propor para seus clientes associar um código de identificação com um meio de pagamento, com os fins de facilitar pagamentos posteriores no site (não é precisa digitar toda vez o número de cartão bancário).

Referência cliente e Token Cartão

Existe 2 tipos de códigos de identificação:

  • A referência cliente (ou Conta cliente). É gerada pelo site de e-commerce e designa a referência do código de identificação de um comprador. O gerenciamento destas contas é livre (por exemplo, pode ser um endereço e-mail acoplado a uma senha, para identificar o cliente no site). As informações sobre a Conta cliente estão armazenadas pelo site de e-commerce.
  • O Token Cartão (ou Identificador do meio de pagamento). Designa um meio de pagamento (cartão bancário, conta bancária, etc...) e um conjunto de dados relativos ao titular deste meio de pagamento. É associado a uma referência cliente (ou Conta cliente). Os dados bancários estão armazenados e assegurados pela plataforma de pagamento que possui a certificação PCI-DSS necessária ao armazenamento dos números de cartões. Somente o Token Cartão é enviado durante as trocas.

Observação: a plataforma de pagamento não realiza nenhuma verificação sobre a unicidade da referência (ou conta de cliente). O token cartão é único e pode ser gerado pelo site do vendedor ou pela plataforma.

Pagamentos com o token cartão

Os Token Cartão possibilitam:

  • Um pagamento em um clique, rápido e seguro. O comprador não precisa mais digitar seus dados bancários durante os pagamentos posteriores. Neste caso, somente haverá uma simples etapa de confirmação com um resumo da transação. Se o meio de pagamento for cartão bancário, o CVV poderá ser requerido nesta etapa, desde que o cartão possua um CVV.
  • O pagamento por assinatura. Para cada conta cliente, serão associados uma recorrência e um valor por um prazo determinado ou indeterminado.

Respeitando certas condições (ver com a plataforma de pagamento), pode-se compartilhar códigos de identificação (Token Cartão) entre diversas entidades jurídicas. Estes códigos de identificação compartilhados entre diversas entidades jurídicas devem ser únicos e devem ser obrigatoriamente gerados pela plataforma de pagamento.

Criação de um token cartão com entrada de caixa

Para criar um Token Cartão, precisa definir o parâmetro formAction. Pode tomar dois parâmetros:

formAction Descrição
ASK_REGISTER_PAY Adiciona uma caixa para assinalar no formulário de pagamento salvar meu cartão
REGISTER_PAY O token será criado automaticamente

Na chamada ao web service Charge/CreatePayment:

    {
        "amount": 990,
        "currency": "BRL",
        "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"];

?>

Ao final do pagamento, o objeto PaymentTransaction terá o token cartão do meio de pagamento na propriedade paymentMethodToken:

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

Criação de um token cartão sem entrada de caixa

Em certos casos, você deseja apenas criar um Token Cartão sem realizar uma cobrança. Para isso, você deve usar o web service Charge/CreateToken:

{
    "currency": "BRL",
    "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"];

?>

A chamada funciona comoCharge/CreatePayment. Uma transação de zero euro será criada. O Token Cartão serão notransactions[0].paymentMethodToken.

Uso de um token cartão na API REST

Se você já registrou um meio de pagamento (Token Cartão), você pode salvar um pagamento usando diretamente o pagamento por Token Cartão. Com esse método, o comprador não precisa digitar as informações do cartão novamente.

Um Token cartão é apresentado desta forma:

Para usá-lo, basta enviar o Token Cartão já criado com o Web Service Charge/CreatePayment .

Exemplo:

    {
        "amount": 990,
        "currency": "BRL",
        "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 retorna diretamente um transação como:

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