Brand identifiers for Cielo acquirer

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 ensure 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 the 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 VerifyCard (Zero Auth), credit card, debit card, and recurring payments, and in the query by PaymentId. The merchant sends them in the request of credit, debit, and own-recurrence MIT transactions. VerifyCard returns the identifiers (response only) and does not receive IssuerTransactionId or TransactionLinkId in the request.

Scheduled recurrence: in subsequent scheduled recurrence transactions, 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 re-authorized transactions;
• TransactionLinkId: mandatory for Mastercard, together with IssuerTransactionId, starting Oct 23, 2026;
• Payment.OriginalRecurrentAmount: mandatory in own recurrence, together with IssuerTransactionId and, for Mastercard, TransactionLinkId.

How to use the identifiers

To ensure the link between related transactions, merchant-initiated transactions (MIT) must reference the identifier of the original cardholder-initiated transaction (CIT) or VerifyCard, or the identifier of the previous MIT in the cycle. The flow expected by card brands and issuers is:

1. The cardholder performs the CIT (or VerifyCard);
2. The card brand returns the identifiers available for that transaction;
3. The merchant stores the returned identifiers and keeps them available for the entire transaction cycle;
4. In subsequent MITs (recurring payments, installments, stored credentials), the merchant sends the received identifiers, linking them to the original transaction;
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 and for the subsequent transactions, which fields the merchant sends and which fields the response returns.

Request example (MIT with IssuerTransactionId and TransactionLinkId)

The example below shows a Mastercard credit MIT linked to the CIT. The IssuerTransactionId and TransactionLinkId values come from the CIT (or VerifyCard) response, and the TransactionLinkId you send must always be the original one.

curl --request POST \
  --url https://apisandbox.braspag.com.br/v2/sales/ \
  --header 'Content-Type: application/json' \
  --header 'MerchantId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  --header 'MerchantKey: 0123456789012345678901234567890123456789' \
  --header 'accept: application/json' \
  --data '
{
  "MerchantOrderId": "2017051001",
  "Customer": {
    "Name": "Aline de Souza"
  },
  "Payment": {
    "Provider": "Simulado",
    "Type": "CreditCard",
    "Amount": 15700,
    "Installments": 1,
    "Capture": true,
    "CreditCard": {
      "CardNumber": "<MASTERCARD_TEST_CARD>",
      "Holder": "Aline de Souza",
      "ExpirationDate": "12/2035",
      "Brand": "Master"
    },
    "IssuerTransactionId": "580027442382078",
    "TransactionLinkId": "Xk7pQ2mR-9wLz_4TbN8vCd",
    "OriginalRecurrentAmount": 14900
  }
}'

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 in: credit and debit authorization, recurring payments, VerifyCard, and query by PaymentId.

Examples:

The following cycle shows the IssuerTransactionId in a Visa credit sale: the CIT request does not send the identifier, the response returns it, and the next MIT sends it.

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

{
  "MerchantOrderId": "2017051001",
  "Payment": {
    "Provider": "Simulado",
    "Type": "CreditCard",
    "Amount": 15700,
    "Capture": true,
    "IssuerTransactionId": "580027442382078",
    "PaymentId": "6f8d1753-86bb-4dc0-9ebb-09a29093e1fb",
    "Status": 2,
    "ReasonCode": 0,
    "ReasonMessage": "Successful",
    "ProviderReturnCode": "6",
    "ProviderReturnMessage": "Operation Successful"
  }
}

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

TransactionLinkId (TLID)

The TransactionLinkId (TLID) is an identifier returned by Mastercard to link cardholder-initiated transactions (CIT) to subsequent merchant-initiated transactions (MIT). It complements IssuerTransactionId and does not replace it: when both are available, store and use both for their respective purposes.

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

Card brand: Mastercard.

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

In the CIT (or VerifyCard), the merchant does not yet have a TLID, because it only exists once the card brand returns it. Therefore, the request does not send the TransactionLinkId field, and Mastercard returns the original identifier in the response, which must be stored for subsequent transactions.

Starting with the second transaction in the cycle, the merchant sends the previously obtained TransactionLinkId in the request. The field is already available in the body of the credit card and debit card APIs. In this case, the response includes two fields:

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

The SentTransactionLinkId field only appears in the response when Cielo sends the TLID to the card brand, regardless of whether the transaction is approved. If it is not sent, the field does not appear, even if the request includes the TransactionLinkId.

Examples:

The following cycle shows the TLID in a Mastercard credit sale: the CIT request does not send the TransactionLinkId, the response returns the identifiers, the next MIT sends them, and the MIT response includes the SentTransactionLinkId and a new TransactionLinkId.

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

{
  "MerchantOrderId": "2017051001",
  "Payment": {
    "Provider": "Simulado",
    "Type": "CreditCard",
    "Amount": 15700,
    "Capture": true,
    "IssuerTransactionId": "580027442382078",
    "TransactionLinkId": "Xk7pQ2mR-9wLz_4TbN8vCd",
    "PaymentId": "6f8d1753-86bb-4dc0-9ebb-09a29093e1fb",
    "Status": 2,
    "ReasonCode": 0,
    "ReasonMessage": "Successful",
    "ProviderReturnCode": "6",
    "ProviderReturnMessage": "Operation Successful"
  }
}

{
  "MerchantOrderId": "2017051002",
  "Customer": {
    "Name": "Aline de Souza"
  },
  "Payment": {
    "Provider": "Simulado",
    "Type": "CreditCard",
    "Amount": 15700,
    "Installments": 1,
    "Capture": true,
    "CreditCard": {
      "CardNumber": "<MASTERCARD_TEST_CARD>",
      "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, consisting of uppercase and lowercase letters (A-Z, a-z), numbers (0-9), hyphen (-), and underscore (_).

TLID in sandbox

In sandbox, the Simulado payment method returns a simulated TransactionLinkId in authorized Mastercard sales and in Mastercard card validation (VerifyCard) with a valid card. This lets you test the TLID cycle before going to production.

TLID implementation phases

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

Original transaction amount in own recurrence

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

The following example shows a Mastercard own-recurrence transaction with the three fields:

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

Sandbox testing

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, 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.

See also

• Card on File
• Transaction initiator indicator (CIT and MIT)
• Create a credit card payment
• VerifyCard by card number
• Get payment details via PaymentId