Skip to main content
Use esta página para entender como pagamentos com cartão via Payment Element são autenticados.

​
O que você precisa fazer

Nada além do que já faz. elements.submit(...) conclui a autenticação do cartão para você quando o pagamento exige. Você não coleta nenhum campo adicional no seu formulário de checkout e não orquestra a autenticação.
A autenticação usa os dados do comprador e da compra que o seu servidor já envia ao criar a transaction — o buyer e os products que você passa para POST /v2/transactions. Mantenha esses dados completos e corretos e a autenticação terá tudo de que precisa.
Envie um cadastro de comprador completo: buyer.email, buyer.name, um buyer.phone com código do país e todos os campos de buyer.address:country, state, city, zipCode, street, number e neighborhood. Apenas o complement é opcional.

​
O que você recebe de volta

submit(...) resolve quando o pagamento chega a um desfecho, tendo havido autenticação ou não. Leia status no resultado:
  • succeeded — o pagamento foi aprovado.
  • processing — o pagamento ainda está sendo resolvido. Aguarde o webhook.
  • failed, refused, canceled, timed_out — a tentativa não passou. Mostre a mensagem retornada e deixe o comprador tentar de novo.
Veja a referência do SDK para a lista completa de status.

​
Se o comprador for interrompido

O comprador pode recarregar a página ou sair no meio do pagamento. Retome a mesma transaction em vez de iniciar uma nova tentativa de checkout:
Persista o id da transaction assim que o seu backend retorná-lo, para que você ainda o tenha depois de um reload.

​
Autenticação de cartão após um reload

Um pagamento que aguardava autenticação de cartão (3DS pré-cobrança) estava vinculado à sessão de Element que capturou o cartão, e um reload inicia uma nova sessão. resume() se auto-corrige: monte um CardElement e chame resume(). O SDK pede que o comprador reinsira o cartão no element montado, retokeniza, comprova que é o mesmo cartão, substitui o desafio obsoleto e conclui a autenticação — resolvendo num resultado terminal. Sem nova tentativa de checkout, sem nova transaction e sem ramificação extra no seu código.
O cartão reinserido precisa ser o mesmo da tentativa original — um cartão diferente é recusado.
Se nenhum card element estiver montado, ou o comprador não reinserir dentro do tempo limite, resume() resolve com um resultado terminal claro pedindo para iniciar uma nova tentativa — nunca entra em loop nem trava.
Integradores avançados que querem sua própria UX de recoleta podem passar manualReentry: true para receber status: "requires_reentry" em vez do auto-heal, e então chamar resume() de novo após recoletar o cartão. Veja a referência do SDK.

​
Estado final

O comprador pode concluir a autenticação depois que o primeiro callback do navegador resolver. Não libere o pedido apenas pelo resultado no navegador — webhook ou reconciliação no servidor é a fonte final de verdade do estado do pagamento.

​
Leia a seguir