Duas formas de pagamento custom homologado

Regras para scripts de parceiros

Introdução

O checkout Wake permite que o comprador pague um pedido com duas formas de pagamento ao mesmo tempo. Exemplos: cartão + Pix, cartão + boleto, Pix + boleto, ou dois cartões. As duas formas aparecem na mesma página e são finalizadas no mesmo clique.

Para a sua forma de pagamento funcionar neste modo, o script precisa conviver com outra forma na página, que pode ter campos com os mesmos nomes que os seus. Um script que funciona com a forma sozinha pode falhar, ou tokenizar o cartão errado, se presumir que é o único na página.

Este documento traz as regras que o script de front do seu conector deve seguir e um checklist para validar antes de pedir a liberação. Os trechos de código são ilustrativos.

Como o script é carregado:

Cada forma de pagamento fica num container próprio, identificado pelo id do pagamento. O script recebe esse id na URL e deve trabalhar só dentro desse container.

<div data-gateway-pagamento="<id do pagamento>">
  <div data-payment-transaction-id="<id do pagamento>">
    <!-- HTML da sua forma de pagamento -->
  </div>
</div>

Parâmetro na URL do script:

  • O script é incluído com pagamento=: .../seu-script.js?...&pagamento=.
  • Se a sua forma aparecer duas vezes no mesmo pedido, o script é incluído uma única vez, com os ids separados por vírgula: pagamento=,.
  • O script pode ser incluído de novo sempre que o comprador trocar de forma de pagamento. A cada nova inclusão, o registro anterior deixa de valer.

Registro:

Fbits.Gateway.Pagamento.Adicionar(idPagamento, validate, pay, loaded);

CallbackQuando é chamadoO que deve fazer
loadedDepois que os scripts da página terminam de carregar. Pode não ser chamado antes de o comprador finalizarAdiantar a inicialização, sem ser indispensável
validateNo clique em finalizar, antes do pagamentoDevolver true se os dados da forma estão válidos e false se não estão
payDepois que todas as formas foram validadasTokenizar e gravar no container o que o pedido precisa/
  • Os callbacks podem ser async, e o checkout aguarda a promessa.
  • Os callbacks das duas formas podem rodar ao mesmo tempo. Não presuma ordem entre elas.
  • Os callbacks recebem {selectedInstallment, totalValue}
    • selectedInstallment é o valor do campo [data-gateway-parcelamento] dentro do seu container;
    • totalValue é o total do pedido, e não o valor que cabe à sua forma.

O que vai no pedido: os campos com name e não desabilitados dentro do seu container:

  • input hidden, text e tel;
  • radio e checkbox marcados;
  • select e textarea.
  • Campo habilitado e com name é enviado, seja ele qual for.

Regras do script:

Regra geral: o container do seu pagamento é o único lugar onde o script lê, escreve e procura elementos.

R1. Registrar cada id recebido

const script = document.currentScript;
const ids = (Fbits.Gateway.Utils.GetParameterByName('pagamento', script.src) || '')
  .split(',').map(s => s.trim()).filter(Boolean);

ids.forEach(id => {
  Fbits.Gateway.Pagamento.Adicionar(id,
    params => validate(id, params),
    params => pay(id, params),
    params => loaded(id, params));
});
  • Trate o pagamento sempre como lista, mesmo que normalmente venha um id só.
  • Cada callback deve conhecer o próprio id, como no exemplo. Não guarde um "pagamento atual" em variável global.

R2. Procurar elementos só dentro do container

const root = document.querySelector(`[data-gateway-pagamento="${id}"]`);
const numero = root.querySelector('input[name="number"]');
  • Não use document.querySelector, document.getElementsByName ou $('...') sem escopo para encontrar campos ou elementos da sua forma. A outra forma pode ter campos com os mesmos name (number, name, month, year, cvc), e a busca na página inteira pode devolver os campos dela.
  • A regra vale para tudo: campos de cartão, select de parcelas ([data-gateway-parcelamento]), banners, mensagens de erro e o local onde o token é gravado.

R3. Não usar id HTML fixo

  • Se a sua forma aparecer duas vezes na página, um id fixo (como #number, #cvc ou #meu-banner) se repete, e getElementById sempre devolve o primeiro.
  • No HTML da sua forma, prefira classes ou atributos data-* e busque a partir do container. Se precisar de id, inclua o id do pagamento nele.

R4. Não alterar nada fora do container

  • Não limpe, esconda, desabilite nem remova name de campos ou elementos fora do seu container.
  • Como os callbacks das duas formas podem rodar ao mesmo tempo, mexer na outra forma faz ela ler dados vazios ou enviar dados errados.

R5. Registrar sempre, mesmo se o script já rodou antes

  • O script pode ser incluído de novo quando o comprador troca de forma de pagamento, e o registro anterior deixa de valer.
  • Não use bloqueios do tipo if (window.MEU_SCRIPT_CARREGADO) return; antes do Adicionar. A forma ficaria sem validate e pay.
  • Se o SDK só pode ser carregado uma vez, proteja apenas o carregamento do SDK. O Adicionar deve rodar a cada inclusão.

R6. Gravar o token no próprio container e falhar se não conseguir

  • Grave o token (campo hidden, com name) diretamente no container [data-payment-transaction-id=""], ou num elemento que você sabe que existe dentro dele.
  • Se o local de destino não for encontrado, o pay deve lançar erro. Um token descartado sem aviso faz o pedido seguir sem token e ser recusado.

R7. Não usar totalValue como valor da forma
Com 2 formas, totalValue é o total do pedido. Se o seu SDK precisa do valor da sua forma (por exemplo, para antifraude ou autenticação), fale com a Wake antes de implementar.


Inicialização e domínios:

R8. Não depender do loaded

  • O loaded pode não ser chamado antes do clique em finalizar. Use-o para adiantar trabalho, mas o validate e o pay devem conferir se o SDK está pronto. Se não estiver, devem inicializá-lo e aguardar antes de seguir.
  • Não dispare a tokenização (por exemplo, um requestSubmit() num formulário do SDK) antes de o SDK estar pronto para recebê-la. Se a inicialização é assíncrona (fingerprint, IP), espere o evento ou a promessa de "pronto".

R9. Informar todos os domínios usados

O checkout só permite recursos de domínios liberados. Recurso de domínio não liberado é bloqueado pelo navegador, e o comprador não recebe aviso.

  • Envie à Wake a lista de domínios de sandbox e de produção de tudo o que o script e o HTML carregam ou chamam: scripts, chamadas fetch/XHR, iframes, imagens (inclusive QR Code e logos) e fontes.
  • Inclua os scripts que o seu SDK carrega por conta própria, como antifraude, 3DS ou carteiras digitais.
  • Avise a Wake antes de trocar ou incluir um domínio.

R10. Tratar elementos ausentes

  • Com 2 formas, a página é diferente da página com a sua forma sozinha. Toda busca no DOM pode voltar vazia: use ?. ou confira antes de usar.
  • Um elemento opcional ausente não pode interromper a montagem do resto da forma.
  • Evite setInterval em loop esperando elementos. Se for inevitável, limite as tentativas, trate exceções e pare o intervalo quando terminar.

Dados de cartão:

R11. Não enviar PAN nem CVV no pedido

  • Ao final do pay, depois de tokenizar, desabilite (disabled = true) ou remova o name dos campos de número do cartão e CVV do seu container. Campos desabilitados ou sem name não são enviados.
  • Garanta que a regra pega os campos certos quando há dois formulários de cartão na página (R2).
  • Envie só o token e os dados não sensíveis de que o seu backend precisa.

R12. Tokenizar o cartão digitado na sua forma

  • Leia número, nome, validade e CVV a partir do container do seu pagamento (R2).
  • No teste com dois cartões, confira na requisição de tokenização que o BIN e os últimos 4 dígitos são os do cartão digitado na sua forma.

Pix, boleto e outras formas sem cartão:

As regras R1 a R10 valem também para formas sem cartão. Além delas:

R13. Montar a forma sem depender de elementos de outra

  • Banner, instruções e formulário da sua forma devem ser montados dentro do seu container, sem procurar elementos que nem sempre existem na página. Exemplo: o select de parcelas de um cartão.
  • A sua forma não pode esconder nem alterar o parcelamento ou os campos de outra forma (R4).
  • Se não há nada a validar, o validate deve devolver true (ou nem ser registrado).

R14. Devolver o QR Code completo

  • Para Pix, a resposta do pagamento deve trazer o código copia e cola, a URL da imagem do QR Code e a data de expiração. Sem a URL da imagem, o QR Code não é exibido ao comprador na confirmação do pedido nem na Minha Conta.
  • O domínio da imagem do QR Code entra na lista de domínios (R9).