Criar cobrança com 3DS

O que é o 3DS?

O 3D Secure (3DS) é um protocolo de autenticação adicional para transações com cartão de crédito. Ele adiciona uma camada de segurança ao verificar a identidade do portador do cartão junto ao banco emissor antes de aprovar a transação. Quando ativado, a transação pode passar por um dos seguintes fluxos:

Rotas que suportam 3DS

Cobranças (Payments)

POST /api/v3/payments — Criar cobrança com cartão de crédito

Cria uma cobrança e já processa o pagamento no cartão se os dados do cartão forem enviados no corpo da requisição.

POST /api/v3/payments/{id}/payWithCreditCard — Pagar cobrança existente com cartão

Processa o pagamento de uma cobrança já criada utilizando cartão de crédito.

Cobranças Lean (Lean Payments)

POST /api/v3/lean/payments — Criar cobrança com cartão de crédito (resposta reduzida)

Funciona da mesma forma que POST /api/v3/payments, porém retorna uma resposta com conjunto de campos reduzido. Também suporta 3DS — o campo threeDSecureChallengeUrl é retornado na resposta lean quando aplicável.

Parcelamentos (Installments)

POST /api/v3/installments — Criar parcelamento com cartão de crédito

Cria um parcelamento e já processa a primeira parcela no cartão se os dados do cartão forem enviados.

POST /api/v3/installments/{id}/payWithCreditCard — Pagar parcelamento existente com cartão

Processa o pagamento de um parcelamento já criado utilizando cartão de crédito.

Contrato de Requisição

Para acionar o 3DS, a requisição deve incluir os objetos threeDSecure e deviceInfo além dos campos padrão da cobrança/parcelamento.

Objeto threeDSecure

Objeto deviceInfo

Informações sobre o dispositivo do pagador, coletadas no browser/app no momento do checkout. Necessárias para que o banco emissor avalie o risco da transação.

Exemplo de requisição (payWithCreditCard)

{
  "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": 180,
    "language": "pt-BR",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...",
    "remoteIp": "200.100.50.25"
  }
}

Contrato de Resposta

Quando o 3DS está habilitado e a cobrança é com cartão de crédito, a resposta inclui o campo adicional:

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
}

Fluxo de Autenticação 3DS

1. Você envia a requisição com os objetos threeDSecure e deviceInfo
2. Se um desafio for necessário, a resposta retorna threeDSecureChallengeUrl
3. Você redireciona o pagador para a URL do desafio
4. O pagador realiza a autenticação no ambiente do banco emissor
5. Após o resultado do desafio, o Asaas:
   • Redireciona o pagador para a callbackUrl informada
   • Envia um webhook para notificar sua aplicação sobre o desfecho (ver seção abaixo)
6. Você aguarda o webhook do Asaas ou consulta o status da cobrança para confirmar o resultado

Notificações via Webhook

Ao final do fluxo 3DS, o Asaas envia um webhook para a URL configurada na sua conta com um dos seguintes eventos: