Criar cobrança com 3DS

O 3D Secure (3DS) é um protocolo de autenticação adicional para transações com cartão de crédito. Ele verifica a identidade do portador do cartão junto ao banco emissor antes de aprovar a transação, o que adiciona uma camada de segurança contra fraudes.

Para acionar o 3DS, envie os objetos threeDSecure e deviceInfo junto com os dados do cartão ao criar ou pagar uma cobrança com cartão de crédito.

Quando utilizar

Utilize o 3DS quando sua integração precisar:

• autenticar o portador do cartão junto ao banco emissor antes da aprovação;
• criar uma cobrança avulsa ou parcelada com cartão de crédito;
• pagar com cartão uma cobrança ou um parcelamento já criado.

Rotas que suportam 3DS

Não existe rota de pagamento no nível do parcelamento. Para pagar um parcelamento já criado, use a rota de cobranças com o id de uma parcela.

Antes de começar

Garanta que:

• o 3DS está habilitado na sua conta de produção. Para habilitar, entre em contato com o nosso time de suporte;
• o cliente está cadastrado e o ID dele está armazenado. Consulte: o Cadastro de clientes;
• sua aplicação recebe Webhooks de cobranças. Consulte os: Eventos para cobranças;
• sua aplicação tem uma URL HTTPS para receber o pagador após o desafio (callbackUrl).

Defina:

• se a cobrança será criada e paga na mesma requisição ou se uma cobrança já criada será paga depois;
• se a venda será uma cobrança avulsa ou parcelada;
• qual página o pagador verá ao voltar do desafio;
• como o seu checkout vai coletar os dados do dispositivo do pagador.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
A["Coletar os dados do dispositivo no checkout"] --> B["Enviar a requisição com threeDSecure e deviceInfo"]
B --> C{"A resposta retornou threeDSecureChallengeUrl?"}

C --> CSim(("Sim"))
C --> CNao(("Não"))

CSim --> D["Redirecionar o pagador para o desafio"]
D --> E["Pagador se autentica no banco emissor"]
E --> F["Asaas redireciona o pagador para a callbackUrl"]
F --> G["Receber o Webhook com o resultado"]
CNao --> G

classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px

classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px

class A inicio
class B validacao
class C decisao
class D,E,F correcao
class G sucesso

class CSim respostaSim
class CNao respostaNao

linkStyle default stroke:#94A3B8,stroke-width:2px
linkStyle 2 stroke:#22C55E,stroke-width:4px
linkStyle 3 stroke:#EF4444,stroke-width:4px

O banco emissor decide qual tipo de autenticação será aplicado:

A resposta da requisição não é a confirmação final quando há desafio. O resultado da autenticação e da captura chega por Webhook.

1. Colete os dados do dispositivo

No momento do checkout, colete no browser ou app do pagador as informações que o banco emissor usa para avaliar o risco da transação.

Exemplo de coleta no browser

const deviceInfo = {
  colorDepth: window.screen.colorDepth,
  screenHeight: window.screen.height,
  screenWidth: window.screen.width,
  timeZoneOffset: new Date().getTimezoneOffset() / 60, // em horas: 180 minutos viram 3
  language: navigator.language,
  userAgent: navigator.userAgent
};

O remoteIp deve ser obtido pelo seu backend, a partir do IP de origem da requisição do pagador.

2. Envie a requisição com threeDSecure e deviceInfo

Inclua os objetos threeDSecure e deviceInfo no corpo da requisição, além dos campos padrão da cobrança ou do parcelamento.

O exemplo abaixo paga uma cobrança já criada:

POST /v3/payments/{id}/payWithCreditCard

Consulte o endpoint: Pagar uma cobrança com cartão de crédito.

Exemplo de requisição

{
  "creditCard": {
    "holderName": "João da Silva",
    "number": "4111111111111111",
    "expiryMonth": "05",
    "expiryYear": "2028",
    "ccv": "123"
  },
  "creditCardHolderInfo": {
    "name": "João da Silva",
    "email": "[email protected]",
    "cpfCnpj": "12345678901",
    "postalCode": "01310-100",
    "address": "Av. Paulista",
    "addressNumber": "100",
    "province": "Centro",
    "phone": "11987654321"
  },
  "threeDSecure": {
    "callbackUrl": "https://seusite.com.br/callback/3ds"
  },
  "deviceInfo": {
    "colorDepth": 24,
    "screenHeight": 900,
    "screenWidth": 1440,
    "timeZoneOffset": 3,
    "language": "pt-BR",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...",
    "remoteIp": "200.100.50.25"
  }
}

Os mesmos objetos são aceitos em POST /v3/payments, POST /v3/lean/payments e POST /v3/installments, junto com os campos de criação da cobrança ou do parcelamento.

3. Redirecione o pagador quando houver desafio

Verifique o campo threeDSecureChallengeUrl na resposta:

• preenchido: o banco emissor exige um desafio. Redirecione o pagador para essa URL;
• null: a autenticação ocorreu de forma silenciosa (DATA_ONLY ou FRICTIONLESS) e não é preciso redirecionar.

Exemplo de resposta com desafio pendente

{
  "id": "pay_xxxxxxxxxxxxx",
  "status": "PENDING",
  "billingType": "CREDIT_CARD",
  "value": 100.00,
  "threeDSecureChallengeUrl": "https://banco-emissor.com.br/3ds/challenge?token=abc123"
}

Exemplo de resposta sem desafio (frictionless ou data-only)

{
  "id": "pay_xxxxxxxxxxxxx",
  "status": "CONFIRMED",
  "billingType": "CREDIT_CARD",
  "value": 100.00,
  "threeDSecureChallengeUrl": null
}

Após o pagador concluir o desafio no ambiente do banco emissor, o Asaas redireciona o pagador para a callbackUrl informada.

4. Acompanhe o resultado por Webhook

Ao final do fluxo 3DS, o Asaas envia um Webhook para a URL configurada na sua conta com um dos eventos abaixo. Você também pode consultar o status da cobrança para confirmar o resultado.

Consulte os: Eventos para cobranças.

Campos importantes

Os campos de deviceInfo não são obrigatórios, mas são usados pelo banco emissor para avaliar o risco da transação. Envie todos os que sua integração conseguir coletar.

Erros comuns

Confirme o resultado

Após a requisição, confirme se:

• a resposta retornou o id da cobrança;
• o pagador foi redirecionado quando threeDSecureChallengeUrl veio preenchido;
• o pagador voltou para a callbackUrl após o desafio;
• sua aplicação recebeu um dos eventos de Webhook do fluxo 3DS;
• o status da cobrança está de acordo com o evento recebido.

Boas práticas

• Colete os dados de deviceInfo no dispositivo do pagador, no momento do checkout.
• Envie timeZoneOffset em horas.
• Redirecione o pagador assim que receber threeDSecureChallengeUrl.
• Use o Webhook ou a consulta da cobrança como confirmação final, e não apenas o retorno do pagador à callbackUrl.
• Trate os três eventos de Webhook do fluxo 3DS.
• Na página da callbackUrl, informe ao pagador que o pagamento está em processamento até receber o resultado.

Referência da API

Próximos passos

• Conheça as cobranças via cartão de crédito
• Crie uma cobrança parcelada
• Acompanhe os eventos das cobranças