Pagamentos

Zero Auth

Quando validar o cartão, quais campos enviar, de onde vem a conta do token e como tratar válido, inválido e indisponível.

Guia de integração · 3 min de leitura

Nesta página

Zero Auth consulta o parceiro para validar um cartão tokenizado sem cobrar. Não confirma saldo, não autentica o portador por 3DS e não garante aprovação de uma compra posterior. Exige suporte e habilitação na conta do parceiro.

Dois caminhos disponíveis

Zero Auth ao salvar token ou no fluxo, sempre antes da autorização do pagamento.

Abrir diagrama em tamanho integral

Necessidade	Onde configurar
Validar antes de salvar um novo token	`POST /v1/customers/{customerId}/payment-methods` com `verify: true`
Validar antes de autorizar compras	Nó Validação de cartão no fluxo, depois de Escolher adquirente, antes de Autorizar pagamento
Validar automaticamente ao salvar	`zeroAuthOnSave` e `zeroAuthEnabled` na configuração da conta compatível

Não há uma API independente POST /zero-auth nem uma rota para consultar um cartão salvo só passando paymentMethodId. Não chame POST /payments com valor zero: pagamento exige valor positivo e não equivale a Zero Auth.

Validar antes de salvar o token

Obtenha customerId de POST /v1/customers; obtenha o card.token no cofre do parceiro e card.connectorAccountId em GET /v1/connector-accounts. Essa conta precisa ser a mesma origem do token. No exemplo abaixo, o token é fictício e pertence ao Minstrel Sandbox.

Validar o token por Zero Auth ao cadastrar

cURL / Bash

curl -X POST "https://api.minstrel.com.br/v1/customers/cus_01M5DA7M63VN499S6P34D6DQJZ/payment-methods" \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Idempotency-Key: post--v1-customers-cus-01M5DA7M63VN499S6P34D6DQJZ-payment-methods" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "card": {
    "token": "tok_sandbox_docs_zeroauth_valid",
    "connectorAccountId": "ca_01M5DA7M27B1RT7R8VPQKJYJF2",
    "brand": "visa",
    "last4": "4242",
    "expMonth": 12,
    "expYear": 2030
  },
  "setDefault": false,
  "verify": true
}'

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

json

{
  "object": "payment_method",
  "id": "pm_01M5DA7NQDMVMAQJDJZBVW255A",
  "customerId": "cus_01M5DA7M63VN499S6P34D6DQJZ",
  "type": "card",
  "brand": "visa",
  "bin": null,
  "last4": "4242",
  "expMonth": 12,
  "expYear": 2030,
  "holderName": null,
  "funding": null,
  "isDefault": false,
  "isNetworkToken": false,
  "verification": {
    "status": "valid",
    "verifiedAt": "2026-10-20T18:47:29.243Z"
  },
  "invalidatedAt": null,
  "invalidatedReason": null,
  "connectorAccount": {
    "id": "ca_01M5DA7M27B1RT7R8VPQKJYJF2",
    "name": "Sandbox - Loja Exemplo",
    "connectorSlug": "minstrel_sandbox",
    "connectorName": "Minstrel Sandbox",
    "enabled": true,
    "removed": false
  },
  "createdAt": "2026-10-20T18:47:29.262Z"
}

Campo	Regra
`card.token`	Obrigatório; token do cofre, nunca número do cartão ou CVV. Para recorrência, precisa ser reutilizável e ter consentimento.
`card.connectorAccountId`	ID `ca_` da conta de origem do token. Não é o slug `cielo` ou `minstrel_sandbox`.
`verify: true`	Exige validação bem-sucedida antes de salvar. Inválido ou indisponível responde 422 e não salva.
`verify: false`	Salva sem validar. Não é indicação de cartão válido.
`verify` omitido	Segue a política `zeroAuthOnSave` da conta; uma indisponibilidade nessa política automática pode permitir salvar.
`setDefault`	Se true, usa o novo cartão como padrão do cliente nas próximas cobranças.

A resposta traz o id pm_ do meio de pagamento e verification com o resultado observado. Guarde o id para usar como paymentMethodId; não use o ID da verificação como se fosse um cartão.

No fluxo de pagamento

Configure Escolher adquirente → Validação de cartão → Autorizar pagamento. As saídas do nó são:

Válido: pode continuar para a autorização, ainda sujeita à decisão do emissor.
Inválido: trate a recusa; não faça repetição técnica desse resultado.
Indisponível: consulta não conclusiva; siga a política que você desenhou.
Erro: falha de execução/configuração; não interprete como cartão validado.

O nó pode reaproveitar uma validação dentro do período configurado, padrão 30 dias. A repetição técnica do próprio Zero Auth aceita de 2 a 3 tentativas com espera e timeout limitados, exclusivamente para falhas transitórias. Ela não repete uma cobrança nem usa a política de retentativa de faturas.

Veja os campos da API de cadastro de token e a diferença entre retentativa técnica e de cobrança.