Card Brand Identifiers

Some card brands return identifiers that make it possible to track and correlate transactions throughout the payment lifecycle, especially in card-on-file, recurring, installment, and other subsequent merchant-initiated transaction scenarios.

These identifiers are important for ensuring traceability, reconciliation, and the link between related transactions. When used correctly, according to card brand and issuer rules, they can also help increase authorization rates because they allow the issuer to identify that a transaction is related to a previous interaction performed by the cardholder.

Currently, Cielo provides the following identifiers returned by the card brands:

Where identifiers are returned and where they are sent

The identifiers are returned in the responses of Zero Auth, credit card, debit card, and merchant recurrence, and in the query by PaymentId. The merchant sends them in the request of MIT transactions of credit card, debit card, and merchant recurrence. Zero Auth returns the identifiers (response only) and does not receive IssuerTransactionId or TransactionLinkId in the request.

Scheduled recurrence: in the subsequent transactions of scheduled recurrence, the IssuerTransactionId and TransactionLinkId fields are sent automatically.

When sending is mandatory

Follow these sending rules in MIT transactions:

• IssuerTransactionId: mandatory for all card brands (Visa, Mastercard, Elo, and American Express) in recurring, incremental, and reauthorized transactions;
• TransactionLinkId: mandatory for Mastercard, together with the IssuerTransactionId, starting October 23, 2026;
• Payment.OriginalRecurrentAmount: mandatory in merchant recurrence, together with the IssuerTransactionId and, for Mastercard, the TransactionLinkId.

How does the card brand identifier flow work?

To ensure the link between related transactions, especially in recurring payments, installments, and card-on-file scenarios, merchant-initiated transactions (MITs) must reference the original client-initiated transaction (CIT).

In this context, the identifiers returned by the card brand in the initial transaction (CIT) must be stored by the merchant and used in subsequent MITs within the same transaction lifecycle.

Expected flow according to card brands and issuers

1. The client performs the CIT transaction (or Zero Auth).
2. The card brand returns the identifiers available for that transaction.
3. The merchant stores the returned identifiers.
4. The merchant links subsequent MITs to the original transaction using the received identifiers.
5. The issuer uses this information to identify the relationship between the transactions and apply its authorization rules.

When to send and when the fields are returned

The following flowchart shows, for a CIT transaction and for the subsequent transactions, which fields the merchant sends and which fields the response returns.

Identifiers provided by card brands

IssuerTransactionId

The IssuerTransactionId is an identifier generated by the card brand or issuer during the authorization process.

This identifier represents the original transaction within the card brand ecosystem and must be used for traceability and correlation of operations related to the same transaction lifecycle.

Card brands: Visa, Mastercard, Elo, and American Express.

Available at: credit and debit authorization, recurring payments, Zero Auth, and query by PaymentId.

Example:

The following cycle illustrates the IssuerTransactionId in a Visa credit card sale: the CIT transaction request doesn't send the identifier, the response returns it, and the next MIT transaction sends it.

{
  "MerchantOrderId": "2017051001",
  "Customer": {
    "Name": "Aline de Souza"
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 15700,
    "Installments": 1,
    "Capture": true,
    "CreditCard": {
      "CardNumber": "<CARTAO_DE_TESTE_VISA>",
      "Holder": "Aline de Souza",
      "ExpirationDate": "12/2035",
      "Brand": "Visa"
    }
  }
}

{
  "MerchantOrderId": "2017051001",
  "Payment": {
    "Type": "CreditCard",
    "Amount": 15700,
    "Capture": true,
    "IssuerTransactionId": "580027442382078",
    "PaymentId": "6f8d1753-86bb-4dc0-9ebb-09a29093e1fb",
    "Status": 2,
    "ReturnCode": "6",
    "ReturnMessage": "Operation Successful"
  }
}

{
  "MerchantOrderId": "2017051002",
  "Customer": {
    "Name": "Aline de Souza"
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 15700,
    "Installments": 1,
    "Capture": true,
    "CreditCard": {
      "CardNumber": "<CARTAO_DE_TESTE_VISA>",
      "Holder": "Aline de Souza",
      "ExpirationDate": "12/2035",
      "Brand": "Visa"
    },
    "IssuerTransactionId": "580027442382078"
  }
}

TransactionLinkId (TLID)

The TransactionLinkId (TLID) is an identifier returned by Mastercard to link client-initiated transactions (CIT) with subsequent merchant-initiated transactions (MIT). The TLID complements the use of IssuerTransactionId and does not replace it.

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

Card brand: Mastercard.

Available in responses from: credit and debit authorization, recurring payments, Zero Auth, and query by PaymentId.

The query by PaymentId returns the TransactionLinkId, but doesn't show the SentTransactionLinkId or the OriginalRecurrentAmount.

First TLID Transaction

In the CIT transaction (or Zero Auth), the merchant does not yet have a stored TransactionLinkId, since this identifier only exists after the card brand returns it.

Therefore, the request for this transaction does not include the TransactionLinkId field. In the response, Mastercard returns a TransactionLinkId, which is the original identifier and must be stored by the merchant for use in subsequent transactions within the same cycle. The Zero Auth request doesn't accept the TransactionLinkId field.

Examples:

The following examples show the CIT request, which doesn't send the TransactionLinkId, and the response, which returns the identifiers.

{
  "MerchantOrderId": "2017051001",
  "Customer": {
    "Name": "Aline de Souza"
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 15700,
    "Installments": 1,
    "Capture": true,
    "CreditCard": {
      "CardNumber": "<CARTAO_DE_TESTE_MASTERCARD>",
      "Holder": "Aline de Souza",
      "ExpirationDate": "12/2035",
      "Brand": "Master"
    }
  }
}

{
  "MerchantOrderId": "2017051001",
  "Payment": {
    "Type": "CreditCard",
    "Amount": 15700,
    "Capture": true,
    "IssuerTransactionId": "580027442382078",
    "TransactionLinkId": "Xk7pQ2mR-9wLz_4TbN8vCd",
    "PaymentId": "6f8d1753-86bb-4dc0-9ebb-09a29093e1fb",
    "Status": 2,
    "ReturnCode": "6",
    "ReturnMessage": "Operation Successful"
  }
}

Subsequent TLID Transaction

Starting with the second transaction in the cycle, the merchant sends in the request the previously obtained TransactionLinkId (from the first transaction or Zero Auth). The field is already available in the body of credit and debit APIs, with request examples:

• Create credit card payment;
• ​Create debit card payment​.

In this case, the response includes two fields:

• SentTransactionLinkId: the value sent by the merchant in the request, which Cielo forwarded to the card brand;
• TransactionLinkId: a new value generated by the card brand for that specific transaction.

The SentTransactionLinkId field appears in the response only when Cielo sends the TLID to the card brand, whether or not the transaction is approved. If Cielo doesn't send the TLID, the field doesn't appear, even if the request includes the TransactionLinkId.

Examples:

The following examples show the MIT request, which sends the identifiers returned in the CIT transaction, and the response with the SentTransactionLinkId and a new TransactionLinkId.

{
  "MerchantOrderId": "2017051002",
  "Customer": {
    "Name": "Aline de Souza"
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 15700,
    "Installments": 1,
    "Capture": true,
    "CreditCard": {
      "CardNumber": "<CARTAO_DE_TESTE_MASTERCARD>",
      "Holder": "Aline de Souza",
      "ExpirationDate": "12/2035",
      "Brand": "Master"
    },
    "IssuerTransactionId": "580027442382078",
    "TransactionLinkId": "Xk7pQ2mR-9wLz_4TbN8vCd"
  }
}

{
  "Payment": {
    "SentTransactionLinkId": "Xk7pQ2mR-9wLz_4TbN8vCd",
    "TransactionLinkId": "aH3nV6qP_2sKe-8YjW1uBf"
  }
}

TLID format

The TransactionLinkId sent in the request must have exactly 22 characters: uppercase and lowercase letters (A-Z, a-z), numbers (0-9), hyphens (-), and underscores (_).

TLID in the sandbox

In the sandbox, the Simulado payment method returns a simulated TransactionLinkId for authorized Mastercard sales and for Zero Auth card validation with a valid Mastercard card. This way, you can test the TLID cycle before you go to production.

TLID implementation phases

TLID implementation is carried out in two phases:

Phase 1 — current

The TransactionLinkId (TLID) is returned in Mastercard authorization responses, including Zero Auth transactions.

In addition to being returned during authorization, the TLID can also be retrieved through the Query API using the transaction's PaymentId.

Phase 2 — October 23, 2026

Starting on October 23, 2026, sending the TransactionLinkId will become mandatory for MIT transactions linked to an original CIT transaction.

Sending the IssuerTransactionId and the OriginalRecurrentAmount is already mandatory and does not depend on these phases.

Original transaction amount in merchant recurrence

In merchant recurrence, send in the Payment.OriginalRecurrentAmount field the amount of the original transaction (first of the cycle), as an integer in cents. The field is mandatory and must be sent together with the IssuerTransactionId and, for Mastercard, the TransactionLinkId.

The following example illustrates a Mastercard merchant recurrence transaction with the three fields:

{
  "Payment": {
    "Type": "CreditCard",
    "Amount": 1500,
    "Recurrent": true,
    "OriginalRecurrentAmount": 1500,
    "IssuerTransactionId": "580027442382078",
    "TransactionLinkId": "mK8vT2qA-9LpX7dWc3Rf_H"
  }
}

Testing in sandbox

In the sandbox environment, the IssuerTransactionId and TransactionLinkId fields are only returned when the transaction uses the Simulado provider and the scenario is an authorized transaction.

Identifier retrieval

If the merchant no longer has the IssuerTransactionId and/or the TransactionLinkId from the original CIT transaction, it is recommended to:

• Prioritize retrieving the identifiers through the query provided by Cielo, using the original transaction information when available;
• If retrieval is not possible, use the identifier from a previous transaction related to the same transaction lifecycle, provided that it appropriately represents the transaction's relationship with the cardholder.

Use in CIT and MIT scenarios

In stored credentials and recurring payment scenarios:

• CIT (Cardholder-Initiated Transaction): transaction initiated by the cardholder — generates the identifier.
• MIT (Merchant-Initiated Transaction): transaction initiated by the merchant — must reference the identifier from the original CIT or the previous MIT.

For more information, see Transaction initiator indicator (CIT and MIT).

See also

• Card On File
• Transaction Initiator Indicator (CIT and MIT)
• Create a credit card payment
• Validate a card with Zero Auth
• Query a transaction by PaymentId