Aplicações web One Page

A integração do formulário embutido segue uma cinemática diferente com sites web cuja lógica é inteiramente gerenciada em JavaScript do lado cliente.

Integração simples

Se seu site usar um framework JavaScript não compilado (JQuery por exemplo), a integração será relativamente simples.

1. Carregamento do formulário de pagamento

A primeira etapa consiste em carregar a livraria JavaScript. Como na integração do lado servidor, basta incluir os scripts JavaScript e as folhas de estilo do formulário embutido.

<head>
    <!-- Javascript library. Should be loaded in head section -->
    <script type="text/javascript"
        src="https://api.lyra.com/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js" 
        kr-public-key="69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5">
    </script>

    <!-- theme and plugins. should be loaded in the HEAD section -->
    <link rel="stylesheet" href="https://api.lyra.com/static/js/krypton-client/V4.0/ext/classic-reset.css">
    <script type="text/javascript" src="https://api.lyra.com/static/js/krypton-client/V4.0/ext/classic.js"></script>

</head>
<body>
    ...
        <!--Hidden payment form -->
        <div id="paymentForm" class="kr-embedded" style="display:none">

            <!-- payment form fields -->
            <div class="kr-pan"></div>
            <div class="kr-expiry"></div>
            <div class="kr-security-code"></div>
    
            <!-- payment form submit button -->
            <button class="kr-payment-button"></button>
    
            <!-- error zone -->
            <div class="kr-form-error"></div>
        </div>
    ...
</body> 
            

Não esqueça de substituir lo campo ‘kr-public-key’ por sua chave pública (ver aqui para maiores detalhes).

2. Inicialização do formulário de pagamento

Quando o usuário decide pagar, você pode iniciar o formulário de pagamento. Para isso, você deve chamar seu servidor Estabelecimento Comercial para verificar nele as compras do usuário, e depois para gerar um código de formulário (chamado formToken) chamando o Web Service Charge/CreatePayment (ainda a partir do seu servidor Estabelecimento Comercial).

/**
* Called on 'checkout' click
*/
function onCheckout()
{
    // Create the order, based on your cart
    var order = {
        "amount":   1190,
        "currency": "EUR",
        "orderId":  "myOrderId-999999",
        "customer": {
            "email": "sample@example.com"
        }
    };

    // Call merchant server to get form token and then display payment form
    getFormToken(order, displayPaymentForm, alert);
}

/**
* Get form token from merchant server
* @param order
* @param resolve
* @param reject
*/
function getFormToken(order, resolve, reject) {
    var request = new XMLHttpRequest();

    // Open a new connection, using the POST request on the URL endpoint
    request.open('POST', 'YOUR_SERVER/payment/init', true);
    request.setRequestHeader('Content-Type', 'application/json');

    request.onload = function () {
        if (request.status >= 200 && request.status < 400) {
            resolve(this.response);
        }
        else
        {
            reject("Invalid server response. Code " + request.status);
        }
    };

    request.onerror = function (error) {
        reject(error);
    };

    // Send request
    request.send(JSON.stringify(order));
}

Do lado servidor, seu código deveria aparecer assim (em Node JS):


/* Init payment form */
router.post('/init', function(req, res, next) {
  var order = req.body;

  // TO DO: check that order is valid  

  // Call CreatePayment web service to create the form token
  request.post({
    url: "https://api.lyra.com/api-payment/V4/Charge/CreatePayment",
    headers: {
      'Authorization': 'Basic Njk4NzYzNTc6dGVzdHBhc3N3b3JkX0RFTU9QUklWQVRFS0VZMjNHNDQ3NXpYWlEyVUE1eDdN',
      'Content-Type': 'application/json'
    },
    json: order
  }, function(error, response, body) {
    if (body.status === 'SUCCESS')
    {
      // Send back the form token to the client side
      res.send(body.answer.formToken);
    }
    else
    {
      // Do your own error handling  
      console.error(body);
      res.status(500).send('error');
    }
  });
});

Importante: não chame o Web Service Charge/CreatePayment a partir do navegador do comprador:

  • A etapa de validação do carrinho é uma etapa crucial, cabe a você verificar nos seus servidores que o valor corresponda ao carrinho antes de enviá-lo.
  • Se chamar o Web Service a partir do navegador do comprador, você colocará a disposição dele (e de piratas potenciais) suas chaves de chamadas, o que é contrário às regras de segurança,
  • A chamada falhará sistematicamente já que nossos servidores não autorizam as chamadas a partir do navegador (Cross Origin Policy).

3. Exibição do formulário de pagamento

Uma vez que o cliente recebeu o formToken gerado do lado servidor, você poderá associá-lo a seu formulário, e exibir este último.

/**
* Display the payment form with the argument form token
* @param formToken
*/
function displayPaymentForm(formToken)
{
    // Show the payment form
    document.getElementById('paymentForm').style.display = 'block';

    // Set form token
    KR.setFormToken(formToken);

    // Add listener for submit event
    KR.onSubmit(onPaid);
}

A última etapa consiste em escutar os eventos do formulário (KR.onSubmit) para ser notificado do lado cliente do final do pagamento.

4. Verificação do status da transação

Uma vez que eu pagamento acabar, que seja aceito ou recusado, você será notificado de duas formas:

  • por uma chamada (IPN) para seu servidor Estabelecimento Comercial, se este último estiver registrado na nossa plataforma de pagamento,
  • por um callback lado JavaScript, registrado no método KR.onSubmit.

Aconselhamos mesmo verificar a integridade da mensagem (ver aqui para maiores detalhes), e iniciar os tratamentos profissionais lado servidor (na recepção do IPN). O callback JavaScript deverá apenas ser usado para retomar o controle do caminho cliente do lado navegador, e exibir a mensagem certa:

/**
  * Called when payment is finished
  * @param event
  */
function onPaid(event)
{
    if (event.clientAnswer.orderStatus === 'PAID')
    {
        // Hide payment form
        document.getElementById("paymentForm").style.display = 'none';

        // Show success message
        document.getElementById("paymentSuccessful").style.display = 'block';
    }
    else
    {
        // Show error message to the user
        alert('Payment failed !');
    }
}

Integração com Vue / React / Angular

Requisitos

A integração do formulário embutido dentro de um site usando frameworks JavaScript compilados (type React ou Angular) requer o uso da biblioteca embedded-form-glue.

Associada ao código JavaScript do formulário embutido, esta biblioteca facilita as operações seguintes:

  • Pré-carregamento da biblioteca para uma exibição mais rápida em redes lentas
  • Gerenciamento da configuração quando a aplicação ainda não foi carregada
  • Permite adicionar, apagar e exibir de novo o formulário facilmente

A biblioteca embedded-form-glue está disponível no github.

Trabalhar em um ambiente assíncrono

Para que você possa integrar o formulário embutido em um ambiente assíncrono, todos os eventos e métodos retornam promessas.

Para cada resolução, a promessa passa um objeto no métodothen()que pode conter duas propriedades:

  • KR: a referência de livraria JavaScript é sempre retornada o que permite ligar as promessas seja qual for o contexto
  • result: o resultado da operação, pode estar não definido ou ausente se nenhum resultado foi retornado
KR.validateForm().then( ({KR, result}) => {
    /* there is no errors */
    /* result == null */
    }
)
.catch( ({KR, result}) => {
    /* Get the error message */
    var code = result.errorCode;
    var message = result.errorMessage;
    var myMessage = code + ": " + message;
    console.log(myMessage);

    /* if you have defined a callback using      */
    /* result.onError(), you can trigger it calling: */
    return result.doOnError();
    }
);

Exemplos de integração

Em função do framework JavaScript que você usa no seu site de e-commerce, outros exemplos de integração estão disponíveis no site github da biblioteca embedded-form-glue.

Framework Descrição
Vue.js exemplo de integração para Vue.js
React exemplo de integração para React
Angular exemplo de integração para Angular e TypeScript

Você pode também integrar a biblioteca embedded-form-glue em qualquer outro framework seguindo os mesmos passos que os exemplos precedentes.