Gerar cobrança Cartão 3DS

Visão geral

ℹ️ Esta rota é a autorização (após o 3DS). A autenticação do comprador com o banco acontece no navegador via authenticate(...) antes de chamar a API. O paymentMethod continua creditcard — a ValidaPay não usa um método threeDs separado.

O fluxo completo tem quatro passos:

1. Tokenizar o dispositivo — collectDevice(...) devolve o deviceId.
2. Autenticar o comprador — authenticate(...) no @validapay/3ds abre o desafio do banco (quando necessário) e devolve authenticationId (e opcionalmente cardId).
3. Tokenizar o cartão — tokenize(...) com o mesmo authentication, gerando um cardToken de 5 minutos vinculado ao cartão autenticado.
4. Autorizar o pagamento (esta rota) — POST /v1/charges com paymentMethod: "creditcard", cardToken, deviceId e authentication.

Para cobrança sem 3DS, use Gerar cobrança Cartão.

Campos do cartão

• cardToken (obrigatório) — vem de tokenize(...) no pacote @validapay/tokenize, gerado depois do authenticate. Vale 5 minutos, é de uso único e só funciona na conta que o gerou.
• deviceId (obrigatório) — vem de collectDevice(...). Identifica o dispositivo e alimenta o antifraude.
• authentication (obrigatório nesta sessão) — resultado de authenticate(...) no @validapay/3ds. Envie exatamente o objeto devolvido:
  • authenticationId (obrigatório)
  • cardId (opcional)

SEU_ID_PUBLICO está no painel em Gerenciamento > Minha Conta > Id Público. É público: pode ficar no código da página.

O valor enviado em amount (ou o total resolvido via items) deve ser o mesmo amount usado no authenticate.

Detalhes do fluxo no front-end: Autenticação do dono do cartão (3DS) e Tokenização de cartão.

Idempotência

Envie externalId como chave de idempotência do pedido. Se duas cobranças forem enviadas com o mesmo valor, a segunda é recusada com 409 DUPLICATE_CHARGE e o corpo traz o chargeId da cobrança original em error.details.chargeId.

⚠️ O cardToken expira em 5 minutos. A idempotência não devolve a resposta da cobrança original: a segunda chamada com o mesmo externalId é recusada com 409 DUPLICATE_CHARGE e o cartão não é reprocessado. Para cobrar de novo, gere um cardToken novo e use outro externalId.

Use externalTxid só para identificar a loja, o caixa ou o vendedor. Ele não entra na idempotência.

Correlação com o pedido: use externalId — ele é persistido e devolvido. O campo metadata é aceito nesta rota, mas não é gravado na cobrança nem volta no webhook.

Produto, valor e parcelas

• Envie items com os produtos ou amount para uma cobrança avulsa — nunca os dois.
• O valor autenticado no 3DS deve bater com o valor cobrado.
• Dá para parcelar com installments e, se quiser, repassar as taxas ao comprador.

Notificações por e-mail

Use notifications para escolher quais e-mails saem nesta cobrança:

• oneoff.payment.success — confirmação ao comprador quando o cartão é aprovado
• oneoff.payment.failed — aviso ao comprador quando o cartão é recusado
• new.sale — avisa você (vendedor) da venda paga

Eventos destinados ao comprador exigem customer.email.

Resposta

• 200 — cartão aprovado: success: true, chargeId, customerId, status: "paid".
• 402 — cartão recusado pelo banco ou adquirente (inclui falha de autenticação 3DS): success: false, status: "failed" e o motivo em error (texto).

Erros comuns

• 400 MISSING_CARD_DATA — faltou o cardToken
• 400 CARD_TOKEN_EXPIRED — passou dos 5 minutos: gere outro na página
• 404 CARD_TOKEN_NOT_FOUND — token inexistente ou de outra conta
• 404 PRICE_NOT_FOUND — o priceId de algum item não existe
• 409 DUPLICATE_CHARGE — o externalId já foi usado; use o chargeId retornado
• 402 — pagamento recusado (card_declined, failed_authentication, insufficient_funds, etc.)

No front-end, erros do SDK 3DS (THREE_DS_FAILED, THREE_DS_TIMEOUT, etc.) ocorrem antes desta chamada — veja Autenticação do dono do cartão (3DS).

Cartões de teste (sandbox)

Em conta de sandbox nenhuma cobrança é cobrada de verdade — o número digitado na tokenização define o resultado:

• 4111111111111111 — aprovado
• 4000000000000002 — recusado (card_declined)
• 4000000000000004 — saldo insuficiente (insufficient_funds)
• 4000000000000006 — cartão expirado (expired_card)
• 4000000000000008 — CVV inválido (invalid_cvv)
• 4000000000000010 — suspeita de fraude (fraud_suspected)

Qualquer outro número de 16 dígitos é aprovado. Em produção o número não muda nada: quem decide é o banco emissor.

Boas práticas

• Sempre autentique e tokenização na sequência, imediatamente antes desta rota. O cardToken expira em 5 minutos.
• Passe o mesmo authentication ao tokenize e à cobrança — assim a ValidaPay guarda o cartão que o banco autenticou (útil em assinaturas).
• Envie deviceId sempre.
• Não confunda falha no SDK com 402. Se authenticate falhar, não chame esta rota.
• Não use metadata para correlacionar o pedido nesta rota — use externalId.