Validar cartão com o Zero Auth

Simula uma autorização para verificar se o cartão está válido no momento.

O exemplo desta página é valido para envio do cartão com os dados abertos (não tokenizados).

ℹ️

Importante

  • Para habilitar o Zero Auth, entre em contato com a equipe de suporte da Cielo. Se a API retornar o código de erro 323, entre em contato com o Atendimento para habilitar a funcionalidade;
  • Para ambiente sandbox, use o cartão 5502095822650000 ou 5315281703921200.
  • O Zero Auth é para clientes que usam a solução API Cielo E-commerce.
❗

Se a resposta for negativa, não submeta o cartão para autorização.

Envie o cartão para autorização apenas se o código de resposta da verificação Zero Auth for positivo.

AmbienteMétodoEndpoint
Sandboxhttps://apisandbox.cieloecommerce.cielo.com.br/1/zeroauth/
Produçãohttps://api.cieloecommerce.cielo.com.br/1/zeroauth/

TLID Mastercard

O Transaction Link Identifier (TLID), enviado e retornado no campo TransactionLinkId, é um identificador único gerado pela bandeira Mastercard durante uma transação CIT, usado para vincular as transações MIT relacionadas. O TLID vale para a resposta do Zero Auth (apenas resposta) e para as transações de crédito, débito e recorrência própria.

Na Mastercard, envie IssuerTransactionId e TransactionLinkId juntos nas transações MIT: os dois parâmetros são obrigatórios.

FaseDescrição
Fase 1Vigente. O campo TransactionLinkId está disponível na resposta da validação de cartão por Zero Auth, criação de pagamento com cartão de crédito, criação de pagamento com cartão de débito e na consulta por PaymentId.
Fase 2Envio obrigatório do TransactionLinkId no request (MIT) a partir de 23/10/2026.

Recorrência programada: nas transações seguintes, os campos IssuerTransactionId e TransactionLinkId são enviados automaticamente.

O TransactionLinkId enviado no request deve ter exatamente 22 caracteres (A-Z, a-z, 0-9, hífen e sublinhado). Se o valor estiver fora desse formato, a Cielo o ignora, sem retornar erro. Quando a Cielo envia o TLID à bandeira, a resposta traz também o SentTransactionLinkId, com o valor enviado. O request do Zero Auth não aceita o campo.

Saiba mais em Identificadores de bandeira.

Requisição

{
  "CardNumber": "5502095822650000",
  "Holder": "Aline de Souza",
  "ExpirationDate": "12/2035",
  "SecurityCode": "123",
  "Brand": "Visa",
  "CardOnFile": {
    "Usage": "First",
    "Reason": "Recurring"
  }
}

A seguir, a listagem de campos da Requisição:

ParâmetroDescriçãoTipoTamanhoObrigatório
CardTypeCreditcard ou DebitCardTexto255Sim
CardNumberNúmero do Cartão do CompradorTexto16Sim
HolderNome do Comprador impresso no cartão.Texto25Sim
ExpirationDateData de e validade impresso no cartão.Texto7Sim
SecurityCodeCódigo de segurança impresso no verso do cartão.Texto4Sim
BrandBandeira do cartão de crédito. Valores aceitos: Visa, Master, Elo e Amex.Texto10Sim
CardTokenObrigatório o envio se estiver informando cartão tokenizado. Token do cartão na API E-commerce Cielo.GUID36Condicional
CardOnFile.UsageFirst se o cartão foi armazenado e é seu primeiro uso.
Used se o cartão foi armazenado e ele já foi utilizado anteriormente em outra transação.
Texto***Não
CardOnFile.ReasonCondicional. Indica o propósito de armazenamento de cartões, caso o campo “Usage” for “Used”. Recurring - Compra recorrente programada (ex. assinaturas). Se for transação recorrente, usar Payment.Recurrent = true (recorrência própria) ou Recurrent.Payment = true (recorrência programada). Unscheduled - Compra recorrente sem agendamento (ex. aplicativos de serviços) Installments - Parcelamento através da recorrência.Texto***Condicional

Resposta da validação no Zero Auth

{
  "Valid": true,
  "ReturnCode": "00",
  "ReturnMessage": "Transacao autorizada",
  "IssuerTransactionId": "580027442382078",
  "TransactionLinkId": "Xk7pQ2mR-9wLz_4TbN8vCd"
}
{
  "Valid": false,
  "ReturnCode": "57",
  "ReturnMessage": "Autorizacao negada",
  }
{
  "Code": 57,
  "Message": "Bandeira inválida"
}
{
  "Code": 389,
  "Message": "Restrição Cadastral"
}
Bad request
Internal Server Error
[
    {
       "ReturnCode": 322,
       "ReturnMessage": "Zero Dollar Auth is not enabled"
    }
  ]

A resposta sempre retorna se o cartão pode ser autorizado no momento. Essa informação apenas significa que o cartão está válido para transacionar, mas não indica que um determinado valor será autorizado.

Os campos retornados na resposta dependem do resultado da validação. A tabela a seguir apresenta todos os campos possíveis.

ParâmetroDescriçãoTipoTamanho
ValidSituação do cartão:
  • True: cartão válido
  • False: cartão inválido
Boolean
ReturnCodeCódigo de retornoString2
ReturnMessageMensagem de retornoString255
IssuerTransactionIdIdentificador da transação gerado pela bandeira, retornado na resposta do Zero Auth. Armazene o valor para enviá-lo nas transações recorrentes seguintes.String30
TransactionLinkIdIdentificador único (TLID) gerado pela Mastercard, retornado na resposta do Zero Auth. Armazene o valor original para enviá-lo, junto com o IssuerTransactionId, nas transações MIT seguintes.String22