Mastercard Transaction Link Identifier (TLID)

March 9, 2026 10:46

Requirement Effective Date: June 2, 2026

Requirement Enforcement Date: October 23, 2026

Overview

Mastercard is introducing the Transaction Link Identifier (TLID) to serve as a persistent reference key across the entire payment lifecycle of a transaction.

To ensure compliance and avoid any potential issuer declines, Adyen is updating its API to expose this identifier.

⚠️ Scope Check: Is this for you?

This guide is ONLY relevant for merchants who:

  1. Process Merchant-Initiated Transactions.

  2. Manage their own Token Vault (External Tokenization) or use a third-party provider.

✅ Using Adyen Tokenization? 

If you use Adyen's Tokenization service (Shopper Reference / Recurring Details), NO ACTION IS REQUIRED. Adyen automatically stores and transmits the TLID on your behalf.

In any scenario, be ready to receive the additionalData.transactionLinkId.

The Requirement

Data Collection: Starting June 2, 2026, Mastercard will begin returning the TLID for all transactions. You must update your integration to receive and store this new field (additionalData.transactionLinkId) alongside your tokenized card data for future MITs.

Requirement Enforcement: By October 23, 2026, for every Recurring Payment or Merchant-Initiated Transaction (MIT), you must provide two distinct identifiers in your payment request:

  1. Trace ID (Existing field: additionalData.networkTxReference)

  2. Transaction Link ID (New field: additionalData.transactionLinkId)

When to send the Transaction Link Identifier

You must include the transactionLinkId when the transaction is classified as a Merchant-Initiated Transaction (MIT). In the Adyen Checkout API, a transaction is classified as an MIT when the request meets all of the following criteria:

  • shopperInteraction: set to ContAuth

  • recurringProcessingModel: set to either Subscription OR UnscheduledCardOnFile

Integration Steps

⚠️ Note regarding API Documentation: Please be aware that the additionalData.transactionLinkId will not appear in the public Adyen API Explorer or standard API reference documentation until the General Availability date of June 2, 2026.

If you are implementing this field during the Pilot phase (mid April – June), please rely strictly on the specifications in this guide. Your schema validation tools will not see this field in our public definitions until the mandate takes effect.

Step 1: Receive & Store the TLID (Available June 2, 2026)

When you process an initial Customer-Initiated Transaction (CIT)—such as the first payment of a subscription or saving a card—Adyen will return the TLID in the authorization response.

You must parse this value and store it alongside your token/card data in your database.

Field Details:

  • Path: additionalData.transactionLinkId

  • Format: 22-character alphanumeric string.

  • Example: oB8FVwXESqe_yZ7q2Snwow

Example API Response:

{

  "pspReference": "8815682123456789",

  "resultCode": "Authorised",

  "additionalData": {

    "networkTxReference": "123456",

    "transactionLinkId": "oB8FVwXESqe_yZ7q2Snwow"

  }

}

Step 2: Send the TLID (Required by October 23, 2026)

For all subsequent Merchant-Initiated Transactions (MITs)—such as a subscription renewal—you must include the stored TLID in your payment request.

Example API Request (e.g. Recurring Payment):

{

  "amount": {

    "currency": "USD",

    "value": 999

  },

  "reference": "Subscription_Renewal_001",

  "shopperInteraction": "ContAuth",

  "recurringProcessingModel": "Subscription",

  "additionalData": {

    "networkTxReference": "123456",

    "transactionLinkId": "oB8FVwXESqe_yZ7q2Snwow"

  }

}

Handling Legacy Recurring Tokens

For tokens created before you updated your integration to store the TLID, your platform will be missing this field.

Strategy:

  1. Process the Next Payment: Process the next recurring payment for your shopper using only the existing networkTxReference.

  2. Read the Response: The response to this payment (even if it is a recurring MIT) will contain a valid transactionLinkId.

  3. Update Your Database: Catch this new TLID from the response and update the token record in your database.

  4. Future Payments: Use this stored TLID for all subsequent payments for that token.

Testing & Validation

To support your integration efforts, the additionalData.transactionLinkId field will be available in both our API Explorer and testing environments ahead of the LIVE rollout.

TEST Environment Availability

  • Availability Start: April 2, 2026

  • Scope: The additionalData.transactionLinkId field will be simulated and provided by default in the TEST environment for all applicable Mastercard payments.

  • No action is required to enable this field. Merchants can begin standard integration and validation testing from this date.

LIVE Environment

  • Go-Live Date: June 2, 2026

  • Scope: The field will be populated in the LIVE environment using real network data from Mastercard.

FAQ

Q: Can I stop sending the networkTxReference (Trace ID) now that I have the TLID? A: No. Mastercard currently requires BOTH identifiers. Removing the Trace ID will result in compliance errors. You must send both until further notice.

Q: What happens if I send a valid networkTxReference but miss the transactionLinkId? A: After June 2, 2026, the issuer may decline the transaction. Adyen cannot generate a static TLID to fix this request.

Q: What is the exact length of the TLID? A: It is a fixed length of 22 characters. Ensure your platform can reconcile this field appropriately (e.g., VARCHAR(22) or larger).