ℹ️
Saiba mais sobre essa funcionalidade na documentação.

Se o estabelecimento usa um gateway ou outro parceiro que já oferece a solução de token de bandeira, é necessário enviar na requisição à API E-commerce Cielo alguns parâmetros específicos para que a bandeira receba os dados do token.

Payment.CreditCard.Cryptogram: é o criptograma do token gerado pela bandeira a cada transação e associa o token à uma transação específica;
Payment.IssuerTransactionId: é o identificador da bandeira para transações de uma série de recorrências (credenciais armazenadas). É importante enviar o Payment.IssuerTransactionId a cada transação para que bandeira e emissor identifiquem que existe uma transação prévia com aquele token (e melhorar as chances de aprovação).

ℹ️
Transações Mastercard
Para transações MIT tokenizadas na bandeira Mastercard, não é necessário enviar o criptograma, pois o token já foi validado previamente na transação CIT original. Ou seja:

em transações CIT, o criptograma deve ser enviado no campo Payment.CreditCard.Cryptogram;

em transações MIT, o criptograma não deve ser enviado.

Caso o criptograma não for enviado, é necessário informar o Payment.IssuerTransactionId.
Saiba mais sobre transações CIT e MIT em Indicador de início da transação - CIT e MIT.

TLID Mastercard

O Transaction Link Identifier (TLID) é um identificador único gerado pela bandeira Mastercard durante uma transação, utilizado para estabelecer a continuidade entre transações relacionadas.

Fase	Descrição
Fase 1	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 a partir de 23/10/2026 (MIT).

Saiba mais em Identificadores de bandeira.

Confira o exemplo de requisição para uso de token de bandeira com integração externa:

Requisição

Ambiente	Método	Endpoint
Sandbox	post	`https://apisandbox.cieloecommerce.cielo.com.br/1/sales`
Produção	post	`https://api.cieloecommerce.cielo.com.br/1/sales`

{
  "MerchantOrderId": "Loja123456",
  "Customer": {
    "Name": "Comprador Teste",
    "Email": "[email protected]",
    "Birthdate": "1991-01-02",
    "Address": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    },
    "DeliveryAddress": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    }
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 15700,
    "Currency": "BRL",
    "Country": "BRA",
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": "ByMerchant",
    "Capture": true,
    "Authenticate": false,
    "SoftDescriptor": "123456789ABCD",
    "CreditCard": {
      "CardNumber": "1234123412341231",
      "CardNumberType":"DPAN",
      "Holder": "Teste Holder",
      "Cryptogram": "abcdefghijklmnopqrstuvw==",
      "ExpirationDate": "12/2030",
      "SecurityCode": "123",
      "SaveCard": "true",
      "Brand": "Visa"
    }
  }
}

Parâmetros no cabeçalho (header)

Parâmetro	Descrição	Tipo	Tamanho	Obrigatório
Content-Type	Tipo de mídia aceito pelo recurso.	String	40	Sim
MerchantId	Identificador da loja na Cielo.	String	36	Sim
MerchantKey	Chave pública para autenticação dupla na Cielo.	String	40	Sim
RequestId	Identificador da requisição, usado quando a loja usa diferentes servidores para cada GET/POST/PUT.	String	36	Não

Parâmetros no corpo (body)

Confira a requisição padrão de cartão de crédito para verificar todos os campos obrigatórios. A tabela abaixo apresenta os parâmetros exclusivos para a tokenização via integração externa.

Parâmetro	Tipo	Tamanho	Obrigatório	Descrição
`Payment.CreditCard.CardNumber`	Texto	19	Sim	Token gerado pela bandeira (DPAN). A indicação de que o `CardNumber` deve ser preenchido com o DPAN para caso de tokenização de bandeira.
`Payment.CreditCard.CardNumberType`	Texto	--	Condicional*	Esse campo suporta os valores PAN e DPAN. Opcional: Quando o cliente envia o Cryptogram. Obrigatório: Quando o cliente envia um cartão tokenizado (DPAN) sem o Cryptogram. Nesse caso, o valor do `CardNumberType` deve ser DPAN.
`Payment.CreditCard.Holder`	Texto	25	Sim	Nome do Comprador impresso no cartão.
`Payment.CreditCard.Cryptogram`	Texto	28	Condicional*	Criptograma gerado pela bandeira. Deve ser enviado caso a tokenização seja feita na bandeira (integração externa).
`Payment.CreditCard.ExpirationDate`	Texto	7	Sim	Data de validade do token gerado pela bandeira.
`Payment.CreditCard.SecurityCode`	Texto	4	Não	Código de segurança impresso no verso do cartão - Ver Anexo.
`Payment.CreditCard.SaveCard`	Booleano		Não (Default false)	Booleano que identifica se o cartão será salvo para gerar o CardToken. Saiba mais sobre Tokenização.
`Payment.CreditCard.Brand`	Texto	10	Sim	Bandeira do cartão (Visa / Master / Amex / Elo / Aura / JCB / Dinners / Discover).

*Deve ser enviado caso a tokenização seja feita na bandeira (integração externa).

Resposta

{
    "MerchantOrderId": "Loja123456",
    "Customer": {
        "Name": "Comprador Teste",
        "Identity":"11225468954",
        "IdentityType":"CPF",
        "Email": "[email protected]",
        "Birthdate": "1991-01-02",
        "Address": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        }
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": true,
        "Authenticate": false,
        "CreditCard": {
            "CardNumber": "455187******0183",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": true,
            "CardToken": "d37bf475-307d-47be-b50a-8dcc38c5056c",
            "Brand": "Visa"
        },
        "ProofOfSale": "674532",
        "Tid": "0305020554239",
        "AuthorizationCode": "123456",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 15700,
        "CapturedAmount": 15700,
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 2,
        "ReturnCode": "6",
        "ReturnMessage": "Operation Successful",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            },
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}

Propriedades da resposta

Parâmetro	Descrição	Tipo	Tamanho	Formato
`ProofOfSale`	Número da autorização, idêntico ao NSU.	Texto	6	Texto alfanumérico
`Tid`	Id da transação na adquirente.	Texto	20	Texto alfanumérico
`AuthorizationCode`	Código de autorização.	Texto	6	Texto alfanumérico
`SoftDescriptor`	Texto que será impresso na fatura bancária do portador - disponível apenas para VISA/MASTER - não permite caracteres especiais	Texto	13	Texto alfanumérico
`PaymentId`	Número de identificação do pagamento, necessário para operações como Consulta, Captura e Cancelamento.	GUID	36	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
`ECI`	Eletronic Commerce Indicator. Representa o quão segura é uma transação.	Texto	2	Exemplos: 7
`Status`	Status da Transação.	Byte		2
`ReturnCode`	Código de retorno da adquirência.	Texto	32	Texto alfanumérico
`ReturnMessage`	Mensagem de retorno da adquirência.	Texto	512	Texto alfanumérico
`Cardtoken`	Token de identificação do Cartão.	GUID	36	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
`Payment.IssuerTransactionId`	Identificador da transação gerado pela bandeira; deve ser enviado para referenciar a transação original/anterior em operações relacionadas, como em recorrências. Consulte mais informações em Identificadores da bandeira.	string	30
`Payment.TransactionLinkId`	O `TransactionLinkId` é um identificador único gerado pela Mastercard para cada transação. O `TransactionLinkId` deve ser usado para vincular a transação inicial com as demais subsequentes. Consulte mais informações em TLID Mastercard . Formato: 22 caracteres alfanuméricos (A-Z, a-z), com diferenciação entre maiúsculas e minúsculas e podem incluir hífens (-) e sublinhados (_).	string	22

post

Criar pagamento com token da bandeira via integração externa

Transações Mastercard

TLID Mastercard

Requisição

Resposta

Próximo

Próximo