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.
| Ambiente | Método | Endpoint |
|---|---|---|
| Sandbox | post | https://apisandbox.cieloecommerce.cielo.com.br/1/zeroauth/ |
| Produção | post | https://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.
| Fase | Descrição |
|---|---|
| Fase 1 | Vigente. 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 2 | Envio obrigatório do TransactionLinkId no request (MIT) a partir de 23/10/2026. |
Recorrência programada: nas transações seguintes, os campos
IssuerTransactionIdeTransactionLinkIdsã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âmetro | Descrição | Tipo | Tamanho | Obrigatório |
|---|---|---|---|---|
CardType | Creditcard ou DebitCard | Texto | 255 | Sim |
CardNumber | Número do Cartão do Comprador | Texto | 16 | Sim |
Holder | Nome do Comprador impresso no cartão. | Texto | 25 | Sim |
ExpirationDate | Data de e validade impresso no cartão. | Texto | 7 | Sim |
SecurityCode | Código de segurança impresso no verso do cartão. | Texto | 4 | Sim |
Brand | Bandeira do cartão de crédito. Valores aceitos: Visa, Master, Elo e Amex. | Texto | 10 | Sim |
CardToken | Obrigatório o envio se estiver informando cartão tokenizado. Token do cartão na API E-commerce Cielo. | GUID | 36 | Condicional |
CardOnFile.Usage | First 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.Reason | Condicional. 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 requestInternal 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âmetro | Descrição | Tipo | Tamanho |
|---|---|---|---|
Valid | Situação do cartão:
| Boolean | |
ReturnCode | Código de retorno | String | 2 |
ReturnMessage | Mensagem de retorno | String | 255 |
IssuerTransactionId | Identificador da transação gerado pela bandeira, retornado na resposta do Zero Auth. Armazene o valor para enviá-lo nas transações recorrentes seguintes. | String | 30 |
TransactionLinkId | Identificador ú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. | String | 22 |