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);
| Callback | Quando é chamado | O que deve fazer |
|---|---|---|
| loaded | Depois que os scripts da página terminam de carregar. Pode não ser chamado antes de o comprador finalizar | Adiantar a inicialização, sem ser indispensável |
| validate | No clique em finalizar, antes do pagamento | Devolver true se os dados da forma estão válidos e false se não estão |
| pay | Depois que todas as formas foram validadas | Tokenizar 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:
inputhidden, text e tel;- radio e checkbox marcados;
selectetextarea.- 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
pagamentosempre 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, egetElementByIdsempre 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
namede 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
Adicionardeve 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
paydeve 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
loadedpode não ser chamado antes do clique em finalizar. Use-o para adiantar trabalho, mas ovalidatee opaydevem 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
setIntervalem 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 onamedos campos de número do cartão e CVV do seu container. Campos desabilitados ou semnamenã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
validatedeve devolvertrue(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).
Updated 1 day ago

