Pagamentos

Autenticação 3DS

Onde o 3DS entra no fluxo, como ler nextAction, quais APIs participam e o que está disponível apenas no simulador.

Guia de integração · 3 min de leitura

Nesta página

3DS autentica a participação do portador antes da autorização. Zero Auth valida o cartão; a autorização pede aprovação financeira; a captura efetiva a cobrança. São etapas diferentes.

Disponibilidade atual

O caminho público de navegador está disponível somente para simulação sem cartão no Minstrel Sandbox, em ambiente sandbox com plugin minstrel_sandbox. As rotas de sessão, confirmação e resultado de 3DS recusam parceiros reais com hosted_checkout_required, inclusive Cielo sandbox.

Para uma integração real, a coleta e a autenticação precisam acontecer em checkout integralmente hospedado pelo parceiro, após homologação dessa integração. Ativar threeDsEnabled ou informar credenciais MPI não libera o caminho suspenso. Veja checkout e dados de cartão.

Onde entra no fluxo

Escolher adquirente, autenticar por 3DS, autorizar e capturar: etapas separadas, com pausa para o portador.

Abrir diagrama em tamanho integral

Desenhe Escolher adquirente → Autenticação 3DS → Autorizar pagamento. A conta escolhida precisa suportar e habilitar o recurso. O modo de autenticação e a saída do nó definem como continuar. Data Only é outro modo de envio de dados; não significa autenticação concluída nem garantia automática de transferência de responsabilidade.

3DS não gera assinatura por si só. A primeira transação pode ser iniciada pelo cliente presente (CIT); os ciclos seguintes seguem as regras MIT e os identificadores da credencial armazenada. Não tente abrir um desafio ao portador ausente a cada renovação.

Sequência de APIs no simulador

Cadastre a conta minstrel_sandbox e o cliente conforme Primeiros passos.
Publique o modelo Checkout com 3DS, com a conta simulada e o recurso habilitado. Copie o flowId do fluxo se quiser selecioná-lo explicitamente.
Crie o pagamento sem card e sem paymentMethodId, informando tokenizationAccountId da conta simulada. O pagamento volta requires_payment_method; guarde id e clientSecret.

Iniciar simulacao de checkout com 3DS

cURL / Bash

curl -X POST "https://api.minstrel.com.br/v1/payments" \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Idempotency-Key: pedido-3ds-001" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "amount": 34990,
  "customerId": "cus_01M5DA7M63VN499S6P34D6DQJZ",
  "tokenizationAccountId": "ca_01M5DA7M27B1RT7R8VPQKJYJF2",
  "flowId": "flw_01M5DA7PJ3XBSENBA0WY16FZ2W",
  "captureMethod": "manual",
  "externalId": "pedido-3ds-001"
}'

HTTP 201 · Resposta completa capturada no Minstrel Sandbox com dados fictícios

json

{
  "object": "payment",
  "security": {
    "transactionFingerprint": "6d98d99c8f5be2be809f1d4444c2a73772353cfe800bb0cc9cd96318c6bf714f",
    "deviceFingerprint": null,
    "cardFingerprint": null,
    "cardIdentitySource": null,
    "channel": "api"
  },
  "id": "pay_01M5DA7PW4RJR1P2YJWFSY1BBV",
  "status": "requires_payment_method",
  "amount": 34990,
  "currency": "BRL",
  "capturedAmount": 0,
  "refundedAmount": 0,
  "captureMethod": "manual",
  "installments": 1,
  "methodType": "card",
  "nextAction": null,
  "actionExpiresAt": "2026-10-21T18:47:30.451Z",
  "initiator": "customer",
  "mitType": null,
  "description": null,
  "softDescriptor": null,
  "externalId": "pedido-3ds-001",
  "customerId": "cus_01M5DA7M63VN499S6P34D6DQJZ",
  "invoiceId": null,
  "paymentMethod": null,
  "decline": null,
  "fraudReview": null,
  "metadata": {},
  "authorizedAt": null,
  "capturedAt": null,
  "failedAt": null,
  "createdAt": "2026-10-20T18:47:30.453Z",
  "updatedAt": "2026-10-20T18:47:30.453Z",
  "clientSecret": "<segredo-retornado-somente-na-sua-requisicao>"
}

Confirme o token fictício na rota pública. O header é Minstrel-Client-Secret, usando o segredo da sua criação. O segredo foi substituído nos exemplos; não copie a marcação como se fosse válido.

Confirmar token ficticio e pausar para 3DS

cURL / Bash

curl -X POST "https://api.minstrel.com.br/v1/public/payments/pay_01M5DA7PW4RJR1P2YJWFSY1BBV/confirm" \
  -H "Minstrel-Client-Secret: $MINSTREL_CLIENT_SECRET" \
  -H "Idempotency-Key: post--v1-public-payments-pay-01M5DA7PW4RJR1P2YJWFSY1BBV-confirm" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "card": {
    "token": "tok_sandbox_docs_3ds",
    "brand": "visa",
    "last4": "4242"
  },
  "saveCard": false
}'

HTTP 200 · Resposta completa capturada no Minstrel Sandbox com dados fictícios

json

{
  "object": "payment",
  "id": "pay_01M5DA7PW4RJR1P2YJWFSY1BBV",
  "status": "requires_action",
  "amount": 34990,
  "currency": "BRL",
  "installments": 1,
  "merchant": {
    "name": "Loja Exemplo - Documentacao"
  },
  "saveCardAllowed": true,
  "nextAction": {
    "type": "three_ds",
    "provider": "minstrel_sandbox",
    "environment": "sandbox",
    "mode": "challenge",
    "order": {
      "number": "pay01M5DA7PW4RJR1P2YJWFSY1BBV",
      "amount": 34990,
      "currency": "BRL",
      "installments": 1,
      "paymentMethod": "credit"
    },
    "billing": {
      "name": "Marina Exemplo",
      "email": "marina@example.invalid",
      "street": "Avenida Exemplo",
      "number": "100",
      "district": "Centro",
      "city": "Sao Paulo",
      "state": "SP",
      "zipCode": "01001000",
      "country": "BR"
    },
    "ipAddress": "127.0.0.1",
    "expiresAt": "2026-10-20T19:02:30.571Z"
  },
  "expiresAt": "2026-10-20T19:02:30.571Z",
  "tokenization": null,
  "deviceFingerprint": null,
  "decline": null,
  "cardAttempts": {
    "used": 1,
    "remaining": 2
  }
}

Só envie o resultado se status for requires_action e nextAction.type for three_ds, dentro do prazo. O exemplo envia um resultado simulado bem-sucedido:

Enviar o resultado simulado do 3DS

cURL / Bash

curl -X POST "https://api.minstrel.com.br/v1/public/payments/pay_01M5DA7PW4RJR1P2YJWFSY1BBV/three-ds" \
  -H "Minstrel-Client-Secret: $MINSTREL_CLIENT_SECRET" \
  -H "Idempotency-Key: post--v1-public-payments-pay-01M5DA7PW4RJR1P2YJWFSY1BBV-three-ds" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "outcome": "success",
  "eci": "05",
  "cavv": "AAABBJg0VhI0VniQEjRWAAAAAAA=",
  "version": "2.2.0",
  "referenceId": "referencia-ficticia-do-sandbox"
}'

HTTP 200 · Resposta completa capturada no Minstrel Sandbox com dados fictícios

json

{
  "object": "payment",
  "id": "pay_01M5DA7PW4RJR1P2YJWFSY1BBV",
  "status": "captured",
  "amount": 34990,
  "currency": "BRL",
  "installments": 1,
  "merchant": {
    "name": "Loja Exemplo - Documentacao"
  },
  "saveCardAllowed": true,
  "nextAction": null,
  "expiresAt": null,
  "tokenization": null,
  "deviceFingerprint": null,
  "decline": null,
  "cardAttempts": {
    "used": 1,
    "remaining": 2
  }
}

Consulte GET /v1/payments/{paymentId} pelo seu backend e acompanhe os webhooks. O resultado acima é a visão pública do pagamento. Com captura manual, aprovação da autorização ainda exige POST /v1/payments/{id}/capture.

Não existe POST /3ds autenticado por chave de API para autenticar qualquer pagamento isoladamente. O 3DS está ligado ao pagamento e ao nó de um fluxo.

Campos do resultado

Campo	Significado
`outcome`	Obrigatório: `success`, `failure`, `unenrolled`, `disabled`, `error` ou `unsupported_brand`.
`eci`	Indicador da bandeira em string, preservando zeros; por exemplo `05` ou `02`, conforme a bandeira e o resultado.
`cavv`, `xid`	Dados transitórios de uma autenticação, não persistidos. Neste simulador, use somente valores fictícios. Não são tokens para cobrar outra vez.
`version`	Versão do protocolo, como `2.2.0`.
`referenceId`	Referência do processo no provedor, diferente de `paymentId`, `flowId` e token do cartão.
`returnCode`, `returnMessage`	Retorno descritivo, sem segredos, para diagnóstico.

Confira campos e respostas da rota simulada. HTTP 409 indica que o pagamento não espera esse resultado; 410 indica prazo encerrado; 429 exige respeitar Retry-After. Não substitua falha de autenticação por aprovação na sua aplicação.