Referência do cliente JavaScript

O cliente JavaScript permite criar um formulário de pagamento no seu site de vendedor, devido ao seguinte código:

<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" 
   content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />  

  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="https://static.payzen.lat/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js" 
   kr-public-key="28478261:testpublickey_LHvSiWObWJnSBv6lnBMmS0tlDPLslOFYXvmKguoWiBIWj" 
   kr-post-url-success="paid.html">
  </script>

  <!-- theme and plugins. should be loaded after the javascript library -->
  <!-- not mandatory but helps to have a nice payment form out of the box -->
  <link rel="stylesheet" 
  href="https://static.payzen.lat/static/js/krypton-client/V4.0/ext/classic-reset.css">
 <script 
  src="https://static.payzen.lat/static/js/krypton-client/V4.0/ext/classic.js">
 </script> 
</head>
<body>
  <!-- payment form -->
  <div class="kr-embedded" 
   kr-form-token="DEMO-TOKEN-TO-BE-REPLACED">

    <!-- 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>
</html>
<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" 
   content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" /> 

  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js"
   kr-public-key="<?php echo $client->getPublicKey();?>"
   kr-post-url-success="paid.php">
  </script>

  <!-- theme and plugins. should be loaded after the javascript library -->
  <!-- not mandatory but helps to have a nice payment form out of the box -->
  <link rel="stylesheet" 
   href="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/ext/classic-reset.css">
  <script 
   src="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/ext/classic.js">
  </script>
</head>
<body style="padding-top:20px">
  <!-- payment form -->
  <div class="kr-embedded"
   kr-form-token="<?php echo $formToken;?>">

    <!-- 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>
</html>

Para ver uma documentação completa, consulte: Iniciar: Pagamento simples

Configurações de inicialização

Diferentes configurações podem ser definidas ao carregar o cliente JavaScript. Por exemplo, para definir kr-public-key e kr-post-url-success:

  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="https://static.payzen.lat/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js" 
   kr-public-key="28478261:testpublickey_LHvSiWObWJnSBv6lnBMmS0tlDPLslOFYXvmKguoWiBIWj" 
   kr-post-url-success="paid.html">
  </script>
  <!-- Javascript library. Should be loaded in head section -->
  <script 
   src="<?php echo $client->getClientEndpoint();?>/static/js/krypton-client/V4.0/stable/kr-payment-form.min.js"
   kr-public-key="<?php echo $client->getPublicKey();?>"
   kr-post-url-success="paid.php">
  </script>

As configurações disponíveis são:

Configuração Requisito Descrição
kr-public-key sim Chave pública a ser utilizada para realizar o pagamento.
kr-language   Idioma de exibição do formulário no formato Culture (pt-BR).
kr-post-url-refused   URL chamado quando todas as tentativas são malsucedidas.
kr-post-url-success   URL para o qual o formulário é POSTado em caso de êxito.
kr-clear-on-error   Desativa a limpeza do CVV em caso de transação recusada (verdadeiro ou falso).
kr-hide-debug-toolbar   Oculta a barra de depuração no modo de teste (verdadeiro ou falso).
kr-placeholder-expiry   Espaço reservado para o campo kr-expiry (data de vencimento).
kr-placeholder-pan   Espaço reservado para o campo kr-pan (número do cartão).
kr-placeholder-security-code   Espaço reservado para o campo kr-security-code (CVV).
kr-spa-mode   if true, form is not automatically initialized. (default is false)

Eventos

É possível anexar retornos de chamada JavaScript personalizados a diversos eventos. O cliente JavaScript é compatível com os seguintes eventos:

Configuração Descrição
KR.onError() Permite receber notificações quando ocorre um erro.
KR.onFocus() Um dos campos do formulário está em destaque.
KR.onFormCreated() O formulário de pagamento está pronto, mas o conteúdo dos iframes ainda não foi carregado.
KR.onFormReady() O formulário já pode ser utilizado.
KR.onLoaded() Primeiro evento chamado antes da criação do formulário.
KR.onSubmit() Chamado logo antes de o formulário ser POSTado.

Todos os eventos retornam promessas, o que lhe permite integrá-los em um string, ver Trabalhar em um ambiente assíncrono para maiores informações.

KR.onError()

KR.onError() permite bloquear os erros antes de eles serem exibidos.

Exemplo de intercepção das mensagens de erro:

  <script type="text/javascript">
    $(document).ready(function() {
          KR.onError( function(event) {
            var code = event.errorCode;
            var message = event.errorMessage;
            var myMessage = code + ": " + message;

            document.getElementsByClassName("customerror")[0].innerText = myMessage;
          });
    });
  </script>

As mensagens de erro estarão em seguida automaticamente exibidas no elemento seguinte, se ele estiver presente:

Quando alguns erros são gerados, eles são agrupados dentro de um erro único. A propriedade children conterá o detalhe de todos os erros:

{
    "errorCode": "CLIENT_300",
    "errorMessage": "Invalid form data",
    "children": [{
        "errorCode": "CLIENT_301",
        "errorMessage": "Invalid card number",
        "field": "pan",
        (...)
    }, {
        "errorCode": "CLIENT_302",
        "errorMessage": "Invalid expiry date",
        "field": "expiryDate",
        (...)
    }, {
        "errorCode": "CLIENT_303",
        "errorMessage": "Invalid security code",
        "field": "securityCode",
        (...)
    }],
    "detailedErrorCode": null,
    "detailedErrorMessage": null,
    (...)
}

Para maiores detalhes sobre os erros, consultar: Gerenciar os erros (cliente JS)

KR.onFocus()

KR.onFocus() permite ser notificado quando um campo do formulário tomo o foco:

Exemplo de integração:

  <script type="text/javascript">
    $(document).ready(function() {
          KR.onFocus( function(event) {
            var myMessage = "focus on: " + event.field;

            $("#custommessage").html(myMessage);
          });
    });
  </script>

Se o campo do número do cartão toma o foco, a variável event terá o valor seguinte:

{
    "field":"pan",
    "formId":"F73867",
    "_type":"krypton/focus"
}

KR.onSubmit()

KR.onSubmit() permite interceptar as informações sobre a autorização autorizada antes de o formulário realizar um POST no URL definido com kr-post-success-url.

Exemplo de integração:

  <script type="text/javascript">
    $(document).ready(function() {
      KR.onSubmit( function(event) {
        /* Change the button label to the orderStatus */
        $(".kr-payment-button > span:first").html(event.clientAnswer.orderStatus);
        $(".kr-spinner").hide();
        $(".kr-payment-button > span:first").show();
        
        /* return values:
         * true: kr-post-success-url is called using POST
         * false: kr-post-success-url is not called, execution stops.
         */
        return false;
      });
    });
  </script>

O objeto contido em event é igual ao POSTado pelo formulário. Para mais detalhes, consulte: Retorno do navegador.

O comportamento varia de acordo com o booliano retornado por sua função:

Valor de retorno Comportamento
false Comportamento por padrão: o cliente JavaScript realiza um POST em kr-post-success-url.
 true O post em kr-post-success-url não é realizado. Você pode gerenciar sozinho a ação post-pagamento.

Métodos

Diversos métodos estão a sua disposição para interagir com o cliente JavaScript:

Configuração Descrição
KR.setFormConfig() Permite fazer alterações a quente na configuração no cliente JavaScript. Consulte a seção a seguir.
KR.setShopName() Muda o nome da loja definido no cabeçalho da pop-in.
KR.setFormToken() Atalho que permite mudar o formToken do formulário atual.
KR.validateForm() Acionar a validação local do formulário.

Todos os eventos retornam promessas, o que lhe permite integrá-los em um string, ver Trabalhar em um ambiente assíncrono para maiores informações.

Consultar a documentação de KR.validateForm() para maiores detalhes:

KR.setFormConfig()

Este método permite mudar na hora os elementos seguintes:

Utilização Descrição
KR.setFormConfig({formToken: “NEW_FORM_TOKEN”}); Alterar o formToken padrão.
KR.setFormConfig({language: “fr-FR”}); Alterar o idioma do formulário de pagamento e das mensagens de erro.

Este método retorna uma promessa (promise).

KR.validateForm()

Este método verifica localmente se o formulário estiver válido. Retorna uma promessa:

  • Then() é chamado quando o formulário estiver válido. result terá o valor nulo.
  • catch() é chamado quando o formulário estiver inválido. result contem o detalhe do erro.

Exemplo de chamada:

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();
    }
);

Uma vez que você interceptou os erros, você pode iniciar o evento KR.onError() manualmente chamandoKR.doOnError();.

Personalização do botão

O botão de pagamento é automaticamente adicionado no seu formulário a partir do código seguinte:

    <!-- payment form submit button -->
    <button class="kr-payment-button"></button>
    <!-- payment form submit button -->
    <button class="kr-payment-button"></button>

Há múltiplas vantagens em usar nosso botão de pagamento:

  • As etiquetas são traduzidas automaticamente
  • O valor é automaticamente formatado e atualizado
  • Nós gerenciamos a animação de espera para você
  • O botão entra automaticamente no modo somente leitura, se necessário

Se você quiser gerenciar sozinho o label do botão, basta adicioná-lo da forma seguinte:

Você pode também inserir uma variável que representa o valor e a moeda. O cliente JavaScript realizará automaticamente a substituição:

Uso avançado

Para ver todos os casos avançados de uso, consulte Funcionalidades do cliente JavaScript.