3DS

O 3D Secure (3DS) é um protocolo de segurança criado para proteger transações com cartão de crédito online, adicionando uma camada extra de autenticação junto ao banco emissor do cartão. Quando habilitado, o cliente precisa confirmar sua identidade antes que a compra seja concluída, reduzindo fraudes e chargebacks e oferecendo mais confiança tanto para quem compra quanto para quem vende.

Por que usar o 3DS?

• Menos fraudes e chargebacks: ao deslocar a responsabilidade para o banco emissor, seu negócio fica protegido em casos de contestação.

• Melhor experiência de checkout: os fluxos modernos (frictionless e challenge) garantem que, na maioria das vezes, o usuário nem perceba a autenticação extra.

• Conformidade: atende exigências de segurança e regulamentações de pagamento (PCI DSS, CERC etc.) .

---

Como funciona o “Liability Shift”

• Liability Shift é a transferência de responsabilidade financeira por fraudes para o banco emissor.

• Se o seller exigir (requiresLiabilityShift = true) e o banco não garantir esse shift, a transação deve ser cancelada.

• Caso contrário, o seller fica protegido contra chargebacks fraudulentos .

---

Passos para integrar o 3DS na Barte

1. Criação do Card Token

   • Chame POST /payment/v1/cards passando os dados do cartão.

   • Guarde o uuid e cardId retornado.

2. Criação da sessão 3DS

   • Chame POST /v1/3ds/session passando o cardId.

   • Você receberá setupId, token (JWT) e collectUrl.

3. Coleta de dados do navegador

   • Insira no front-end um script que submeta token para collectUrl via iframe.

   • Aguarde o evento message que sinaliza o fim da coleta (~1 segundo).

4. Criação da ordem (order)

   • Use POST /v2/orders, incluindo o objeto threeDSecure com setupId, redirectURL, dados de browser e flags (dataOnly, requiresLiabilityShift).

   • Se challenged = true, prepare o fluxo de Step Up Challenge.

5. Step Up Challenge (se necessário)

   • Exiba um iframe/form com o stepUrl e token retornados em threeDSecure.auth.

   • Ao concluir, o usuário volta para a sua redirectURL.

6. Consulta de status da ordem

   • Chame GET /v2/orders/{orderUuid} para verificar se a transação está APPROVED, DECLINED ou outro status.

   • Se APPROVED, finalize a venda; se DECLINED, exiba erro; em outros casos, aguarde.

---

Considerações importantes

⚠️ O teste real de 3DS só funcionará em ambiente de produção e com um front-end estruturado para rodar os scripts. O teste via Postman/Insomnia entre outros não funcionará.

• Possuímos cartões de teste para validar cada cenário do challenge em produção.

• dataOnly = true: coleta apenas dados de risco, sem challenge e sem liability shift.

• requiresLiabilityShift: se true e não houver shift, cancele a transação.

• challenged: quando true, redirecione o cliente para a redirectURL.

• Dados de browser: obrigatórios em todos os fluxos 3DS2 para análise antifraude.

• Sempre trate todos os campos de threeDSecure, mesmo em fluxos simples, para garantir robustez.