ℹ️
Learn more about this feature in the documentation.

If the merchant uses a gateway or another partner that already offers the network token solution, it is necessary to send some specific parameters in the request to the Cielo E-commerce API so that the card network receives the token data.

Payment.CreditCard.Cryptogram: this is the token cryptogram generated by the card network for each transaction and associates the token with a specific transaction;
Payment.IssuerTransactionId: this is the card network's identifier for transactions in a series of recurrences (stored credentials). Send the Payment.IssuerTransactionId in each recurring MIT transaction, because sending is mandatory: it allows the card brand and issuer to identify the previous CIT transaction with that token.

ℹ️
Mastercard transactions
For tokenized MIT transactions on the Mastercard card brand, there is no need to send the cryptogram, because the token was already validated in the original CIT transaction. In other words:

in CIT transactions, the cryptogram must be sent in the Payment.CreditCard.Cryptogram;

in MIT transactions, the cryptogram must not be sent.

If the cryptogram is not sent, the merchant must send the Payment.IssuerTransactionId.
See more about CIT and MIT transactions at Transaction Initiator Indicator.

TLID Mastercard

The Transaction Link Identifier (TLID), sent and returned in the TransactionLinkId field, is a unique identifier generated by the Mastercard card brand during a CIT transaction, used to link the related MIT transactions. The TLID applies to the Zero Auth response (response only) and to credit card, debit card, and merchant recurrence transactions.

For Mastercard, send IssuerTransactionId and TransactionLinkId together in MIT transactions: both parameters are mandatory.

Phase	Date	Description
Phase 1	Current	Availability of the `TransactionLinkId` in the responses of card validation by Zero Auth, credit card payment creation, debit card payment creation, and in the query by `PaymentId`.
Phase 2	Starting October 23, 2026	Required inclusion of the `TransactionLinkId` in the request (MIT).

See more details in Card Brand Identifiers.

Check out the example request for using a card token with external integration:

Request

Environment	Method	Endpoint
Sandbox	post	`https://apisandbox.cieloecommerce.cielo.com.br/`
Production	post	`https://api.cieloecommerce.cielo.com.br/`

Header parameters

Parameter	Description	Type	Size	Required
Content-Type	Media type accepted by the resource.	String	40	Yes
MerchantId	Store identifier in Cielo.	String	36	Yes
MerchantKey	Public key for dual authentication in Cielo.	String	40	Yes
RequestId	Request identifier, used when the store uses different servers for each GET/POST/PUT.	String	36	No

Body Parameters

Check the standard credit card request to verify all mandatory fields. The table below presents the exclusive parameters for tokenization via external integration.

Parameter	Type	Size	Required	Description
`Payment.CreditCard.CardNumber`	Text	19	Yes	Token generated by the brand (DPAN). Indication that the `CardNumber` should be filled with the DPAN in case of brand tokenization
`Payment.CreditCard.CardNumberType`	Text	--	Conditional	This field supports the values PAN and DPAN. Optional: When the customer sends the Cryptogram. Required: When the customer sends a tokenized card (DPAN) without the Cryptogram. In this case, the value of `CardNumberType` must be DPAN.
`Payment.CreditCard.Holder`	Text	25	Yes	Buyer's Name printed on the card.
`Payment.CreditCard.Cryptogram`	Text	28	Conditional	Cryptogram generated by the brand. Must be sent if tokenization is done by the brand (external integration).
`Payment.CreditCard.ExpirationDate`	Text	7	Yes	Expiration date of the token generated by the brand.
`Payment.CreditCard.SecurityCode`	Text	4	No	Security code printed on the back of the card - See Attachment.
`Payment.CreditCard.SaveCard`	Boolean		No (Default false)	Boolean that identifies if the card will be saved to generate the CardToken. Learn more about Tokenization.
`Payment.CreditCard.Brand`	Text	10	Yes	Card brand (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover).

Must be sent if tokenization is done by the brand (external integration).

Example of the request

{
  "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"
    }
  }
}

Response

{
    "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"
            }
        ]
    }
}

Response property

Parâmetro	Descrição	Tipo	Tamanho	Formato
`ProofOfSale`	Authorization number, identical to NSU.	Text	6	Alphanumeric text
`Tid`	Transaction ID at the acquirer.	Text	20	Alphanumeric text
`AuthorizationCode`	Authorization code.	Text	6	Alphanumeric text
`SoftDescriptor`	Text to be printed on the cardholder's bank statement - available only for VISA/MASTER - does not allow special characters	Text	13	Alphanumeric text
`PaymentId`	Payment identification number, required for operations such as Query, Capture, and Cancellation.	GUID	36	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
`ECI`	Electronic Commerce Indicator. Represents how secure a transaction is.	Text	2	Example: 7
`Status`	Transaction Status.	Byte		2
`ReturnCode`	Acquirer return code.	Text	32	Alphanumeric text
`ReturnMessage`	Acquirer return message.	Text	512	Alphanumeric text
`Cardtoken`	Card identification token.	GUID	36	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
`Payment.IssuerTransactionId`	Transaction identifier generated by the card brand and returned in the CIT transaction. Send the value in MIT transactions: sending is mandatory, for all card brands, in recurring, incremental, and reauthorized transactions. See more details in Card Brand Identifiers.	string	30	Alphanumeric text
`Payment.TransactionLinkId`	Unique identifier (TLID) generated by Mastercard and returned in the CIT transaction, used to link the CIT transaction to subsequent MIT transactions. For Mastercard, send the original `TransactionLinkId` together with the `IssuerTransactionId`: both are mandatory, and sending the `TransactionLinkId` is mandatory starting October 23, 2026. See more details in Card Brand Identifiers. Format: 22 alphanumeric characters (A–Z, a–z), case-sensitive, and may include hyphens (-) and underscores (_).	string	22	Alphanumeric text