Mastercard Transaction Link Identifier (TLID)
The Mastercard Transaction Link Identifier (TLID) is a 22-character alphanumeric identifier assigned by Mastercard to deterministically link all lifecycle events in a transaction chain — including captures, refunds, reversals, and merchant-initiated transactions (MITs) — to the original authorization. EBANX handles TLID extraction, storage, and echoing transparently, requiring no changes to your existing API integration.
Context
Mastercard's global mandates (AN 7102, GLB 8390.2, and GLB 8701.4) require the replacement of legacy PAN-based trace identifiers with the TLID. Acquirers are rolling out enforcement timelines, with full compliance required by 2027. The TLID enables deterministic transaction matching for disputes and recurring billing, replacing probabilistic methods that rely on legacy Trace IDs.
How it works
When a Mastercard credit card payment is authorized, the TLID is generated by Mastercard and returned to EBANX through the acquirer's authorization response. EBANX extracts and stores the TLID alongside the original transaction record, and includes it in the payment response sent back to the merchant. For any subsequent lifecycle event — such as a capture, refund, reversal, or recurring charge — EBANX retrieves the original TLID and injects it into the outbound request sent to the acquirer, proving the deterministic linkage of the transaction chain.
TLID support requires the acquirer processing the transaction to be compliant with Mastercard's mandate. Not all acquirers have implemented TLID yet. As acquirers adopt the standard, EBANX will automatically enable TLID for the corresponding transaction flows — no action is required from merchant side.
Benefits
| Benefit | Description |
|---|---|
| Chargeback dispute matching | The TLID enables deterministic transaction linking for chargeback representations, significantly improving dispute win rates compared to legacy probabilistic matching. |
| Recurring billing continuity | Merchant-initiated transactions (MITs) for recurring charges are linked to the original customer-initiated transaction (CIT), reducing the risk of decline codes due to missing transaction linkage. |
| Network compliance | EBANX maintains compliance with Mastercard's evolving network mandates, protecting merchants from potential network fines or processing restrictions. |
Response examples
When available, the TLID is returned inside the transaction_references array in the payment response. Below are examples for the /ws/direct and /ws/query endpoints.
/ws/direct
{
"payment": {
"hash": "6a15e96fd9741f92e1b04f7863b05729801ec62843134ec3",
"transaction_references": [
{"name": "tlid", "value": "000000000000002"}
]
}
}
/ws/query
{
"payment": {
"hash": "6a15e96fd9741f92e1b04f7863b05729801ec62843134ec3",
"transaction_references": [
{"name": "tlid", "value": "000000000000002"}
],
"refunds": [
{
"id": "1449603",
"transaction_references": [
{"name": "tlid", "value": "000000000000002"}
]
}
]
}
}
Impact on your integration
EBANX manages the full TLID lifecycle — extraction, persistence, and echoing — transparently. No changes to your API requests are required. The TLID is returned in the transaction response, and merchants can optionally consume this data for their own reconciliation or dispute management purposes.
Your existing integration continues to work without modification. EBANX provides the TLID in the transaction response as additional data that you can choose to use or ignore. No new fields, parameters, or headers are required in your requests.
The TLID applies to Mastercard credit card transactions only. Visa, Elo, and other card network transactions are not affected by this mandate and continue to operate under their existing transaction linking mechanisms.
Merchants may reach out to the EBANX Integration Specialists for more information and to check availability.
Still need help?
We hope this article was helpful. If you still have questions, you can explore the following options:
- Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
- Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.
