Mastercard Transaction Link Identifier (TLID)

​

What the TLID is

The Mastercard Transaction Link Identifier (TLID) links every payment in a stored credential series back to the customer-initiated payment that started it. Mastercard generates the TLID on that first customer-initiated transaction (CIT) and returns it in the authorization response. Mastercard began returning the TLID on June 2, 2026. From October 23, 2026, Mastercard requires the TLID on every later merchant-initiated transaction (MIT) in a stored credential series, such as a subscription renewal or an unscheduled card-on-file charge. The TLID runs alongside the existing scheme transaction ID, also known as the Mastercard trace ID. It doesn’t replace it, and Gr4vy continues to send both.

​

How Gr4vy handles the TLID

On a supported connector, Gr4vy handles the TLID for you:

1. Gr4vy reads the TLID from the response to the first customer-initiated payment in a series.
2. Gr4vy stores the TLID with the stored payment method.
3. On each later merchant-initiated payment with that payment method, Gr4vy sends the TLID to the connector automatically.

No integration changes are needed, unless your payment service provider (PSP) has to switch the TLID on for your account. See enabling the TLID with your PSP. This relies on each transaction being flagged correctly as customer-initiated or merchant-initiated. Set payment_source, merchant_initiated, and is_subsequent_payment as described in the recurring payment flags and common scenarios.

​

API fields

The TLID appears in the API as follows: You can supply your own TLID in two ways:

• Per transaction - Set previous_transaction_link_id when you create a merchant-initiated transaction. If you leave it out and the stored payment method has a qualifying earlier customer-initiated transaction, Gr4vy fills it in with the TLID returned for that transaction.
• On the payment method - Set transaction_link_id when you update a payment method. Gr4vy then sends that value on later merchant-initiated transactions with the payment method.

If you process merchant-initiated transactions without a stored payment method, pass the transaction_link_id from the first transaction as previous_transaction_link_id on each later transaction.

​

Series that started before June 2, 2026

A stored credential series that started before June 2, 2026 has no TLID on file, because Mastercard didn’t return one at the time. For these series, Gr4vy only sends a TLID when one is stored on the payment method or supplied in the request. If you hold a TLID for such a series, for example from your acquirer, store it on the payment method or pass it as previous_transaction_link_id.

​

Connector coverage

The following table shows TLID support by connector.

​

Supported

​

Supported with PSP action

​

Handled by the provider

For these closed-loop connectors, cards are stored with the provider, which keeps and replays the TLID itself. Nothing is needed from you or from Gr4vy.

​

Not yet supported

​

Enabling the TLID with your PSP

For the following connectors, Gr4vy supports the TLID, but your PSP has to act before it reaches Mastercard.

• Ecommpay - For Gr4vy to receive the TLID, Ecommpay must turn on the TLID callback parameters for your production project. Ask your Ecommpay contact to enable them.
• Nuvei - Nuvei must enable the TLID on each merchant account. Ask your Nuvei account manager. Until it’s enabled, Nuvei accepts the TLID without an error but doesn’t pass it on to Mastercard.
• Worldline TravelHub - Worldline is still rolling out the field, so confirm availability with Worldline. If you process through Navitaire, Sabre, or Outpayce, take it up with that partner instead.
• Worldpay WPG - Worldpay must enable the TLID on your merchant code. Ask your Worldpay account manager.
• Wpay - Wpay forwards the TLID to the scheme only once its own switch upgrade is in place. Confirm the timing with Wpay.