Mastercard Transaction Link ID (TLID)

The Mastercard Transaction Link ID (TLID) is a unique identifier that Mastercard generates for transactions on the Mastercard network. The TLID links the messages that belong to a transaction: authorization, incremental authorization, reversal, and clearing. It also links related transactions, such as an initial subscription sign-up and each renewal.

Use the TLID to keep every message and renewal in a payment agreement connected on the Mastercard network. If you save card credentials in the Braintree Vault, Braintree handles the TLID for you.

Know before you code

Review the following topics before you change your integration:

• Account Updater
• Braintree GraphQL API reference
• Recurring Billing
• Transaction Lifecycle

About TLID

Mastercard generates the TLID, and Braintree returns it in the transaction response. Every transaction that routes over the Mastercard network carries a TLID, regardless of card brand. This includes co-branded debit transactions that route over the Mastercard network at authorization.

TLID and Network Transaction identifier (NTI)

The TLID works alongside the network transaction ID, also known as the Trace ID. Mastercard currently requires both identifiers for MITs, so keep sending the Trace ID.

Check whether you need to act

The requirement applies if you process MITs or recurring payments on cards that route over the Mastercard network. Your action depends on where you save card credentials.

If you save cards in the Braintree Vault, Braintree saves the TLID from the original CIT or card verification with the vaulted payment method. Braintree sends the TLID on your later MITs, including after Account Updater card changes. The TLID can still appear in your transaction responses.

If you save cards outside Braintree, you're responsible for the TLID. This applies to your own vault, a third-party vault, and an orchestrator. Save the TLID from each original CIT. Then send the TLID and the network transaction ID with every MIT through the external vault parameters.

Implementation phases

Mastercard introduces the TLID in phases. Braintree supports phases 1 and 2a for you.

If you use the Braintree Vault, Braintree handles phase 2b for you.

Implement TLID for cards saved outside Braintree

Complete the following steps if you save card credentials in your own vault, a third-party vault, or an orchestrator.

Save TLID from original CIT

When you process the first payment for a card that you plan to reuse, Braintree returns the TLID in the authorization response. First payments include a subscription sign-up, a saved-card payment, and a zero-amount card verification. Save the TLID with your saved card or token, next to the network transaction ID that you already save.

The TLID is echoed back in the auth response in the mastercard-transaction-link-id field. The GraphQL API returns the TLID in the processorResponse.mastercardTransactionLinkId field. The Java, Python, Ruby, and PHP SDKs support this field. Check the SDK release notes for the .NET and Node.js SDK versions that support this field.

Sample response

A response with a 22-character TLID value confirms that the card is ready for later MITs. Save this value with your saved card or token.

The XML API returns the following response:

<transaction>
  <id>6h8b4j5t</id>
  <status>authorized</status>
  <type>sale</type>
  <network-transaction-id>020260602133839</network-transaction-id>
  <mastercard-transaction-link-id>jhsKQkvCeyiUdgjz20b959</mastercard-transaction-link-id>
</transaction>

The GraphQL API returns the following response:

{
  "transaction": {
    "id": "sdfsff",
    "status": "AUTHORIZED",
    "processorResponse": {
      "mastercardTransactionLinkId": "jhsKQkvCeyiUdgjz20b959"
    }
  }
}

Send TLID with every MIT

Pass the saved TLID in the external vault options on each recurring payment or MIT, next to the existing network transaction ID. Keep sending both identifiers. Mastercard requires the original TLID on MITs starting October 23, 2026.

Code sample

Use the following code samples to test in the sandbox. Before you go live, see the GraphQL API reference to update the values for your live integration.

This API uses the GraphQL API endpoint. The following GraphQL sample adds the TLID to the external vault input:

externalVault: {
  status: VAULTED,
  previousNetworkTransactionId: "ORIGINAL-TRACE-ID",
  previousMastercardTransactionLinkId: "ORIGINAL-TLID"
}

The following Ruby sample adds the TLID inside :external_vault:

Braintree::Transaction.sale(
  amount: "9.99",
  payment_method_token: "PAYMENT-METHOD-TOKEN",
  external_vault: {
    status: "vaulted",
    previous_network_transaction_id: "ORIGINAL-TRACE-ID",
    previous_mastercard_transaction_link_id: "ORIGINAL-TLID"
  }
)

Handle cards saved before TLID

If you saved a card before you began saving TLIDs, capture the TLID from the next payment for that card. Complete the following steps:

1. Process the next recurring payment with only the existing network transaction ID.
2. Read the TLID from the authorization response for that payment.
3. Save the TLID to the card record.
4. Send the saved TLID on all later payments for the card.

If you need historical TLIDs from Mastercard for a large base of older cards, contact your Braintree account team.

Pre-launch checklist

Confirm the following items before you go live:

• Confirm that your orchestrator or third-party vault passes the TLID through to Braintree
• Read and save the TLID from authorization responses for all new CITs and zero-amount verifications
• Save the TLID for each card and agreement in a case-sensitive field of at least 22 characters
• Send both the Trace ID and the TLID from the original CIT on every MIT and recurring payment

SDK availability

Update your integration to the following SDK versions. Reading the TLID from the response and sending it on MITs are supported from different versions.

Frequently asked questions

The following answers cover the most common questions about the TLID and how it affects your Braintree integration.

Who needs to take action

The requirement applies if you process MITs or recurring payments and save card credentials outside the Braintree Vault. If you use the Braintree Vault, Braintree saves and sends the TLID for you.

Trace ID after TLID

Keep sending the network transaction ID. Mastercard requires both identifiers until it announces otherwise, and they aren't interchangeable.

Missing or incorrect TLID

Mastercard doesn't decline a transaction only because the TLID is missing or not correct. If the TLID that you send doesn't match, Mastercard replaces it with the correct value and flags the transaction.

TLID for renewals

Send the TLID from the original CIT or zero-amount card verification that established the agreement. Braintree sends the lifecycle TLID for the renewal itself.

Braintree Vault changes

Braintree handles the TLID if you use the Braintree Vault. Braintree saves the TLID with the vaulted payment method and adds it to later MITs.

Orchestrators and third-party vaults

You're responsible for the TLID if you use an orchestrator or a third-party vault. Be sure that your vault provider saves the TLID from the original CIT and supports passing it to Braintree in the external vault parameters.

TLID format

The TLID is exactly 22 characters. It contains letters, digits, hyphens, and underscores, and it's case-sensitive.

TLID and Payment Account Reference

The Payment Account Reference (PAR) links different payment tokens that share the same underlying card account. The TLID links the messages and related transactions that belong to the same transaction chain. Your data model might need both.

Cards saved years ago

Send the Trace ID as you do today. Then capture the TLID from the next authorization response and save it with the card.

Legacy identifier retirement

Mastercard plans to retire the Banknet Reference Number, Trace ID, and Switch Serial Number in 2027 or later. Mastercard hasn't set a fixed date and gives advance notice.

Fees and interchange

The TLID is a data requirement. It doesn't change fees or interchange.

What's next

• Get help with your Braintree account
• Review the Braintree SDK documentation