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. Merchants must store the TLID returned by EBANX and include it in subsequent MIT requests via the transaction_references field; in cases where the original CIT was processed by another PSP, the TLID from that CIT transaction must also be provided.
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 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 supported lifecycle events — such as captures, refunds, and reversals linked to a known EBANX transaction — EBANX uses the TLID associated with the original authorization. For merchant-initiated transactions (MITs), the TLID must be submitted whenever available, using the TLID from the original CIT — whether processed by EBANX or another PSP. Storing this identifier is the merchant's responsibility.
Merchants may also send a TLID in the payment request using the transaction_references field. When provided, EBANX validates and stores the merchant-supplied TLID alongside the transaction record.
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 — merchants submitting MITs must still provide the TLID via transaction_references when available.
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 | When merchants retain and supply the original CIT's TLID in subsequent MIT requests, deterministic transaction linkage is established, reducing the risk of decline codes associated with missing or incomplete lifecycle references. |
| Network compliance | EBANX maintains compliance with Mastercard's evolving network mandates, protecting merchants from potential network fines or processing restrictions. |
Sending the TLID in a request
When available, merchants must include the TLID in the payment request by adding a transaction_references array to the request body. This is useful for use cases where the merchant needs to explicitly link the transaction to a known TLID — for example, when resubmitting a transaction or when the merchant manages their own transaction linking.
Request example — /ws/direct
{
"integration_key": "{{integration_key}}",
"payment": {
"merchant_payment_code": "{{unique_merchant_code}}",
"amount_total": 99.85,
"currency_code": "BRL",
"payment_type_code": "creditcard",
"transaction_references": [
{"name": "tlid", "value": "0000000000000000000002"}
]
}
}
The transaction_references field must be provided when the TLID is available. Supplying it ensures correct transaction linkage and may improve processing performance. When omitted, EBANX continues to handle TLID extraction and storage from the acquirer's authorization response where supported.
Response examples
When available, the TLID is returned inside the transaction_references array in the payment response. This applies to successful transactions and, when the acquirer returns the TLID during the authorization attempt, to declined transactions as well. Below are examples for the /ws/direct and /ws/query endpoints.
Successful payment — /ws/direct
{
"payment": {
"hash": "59acc5f00945fa382ab051651440826da7701533249b3a475",
"status": "CO",
"transaction_references": [
{"name": "tlid", "value": "0000000000000000000002"}
]
},
"status": "SUCCESS"
}
Declined payment — /ws/direct
{
"payment": {
"hash": "59acc5f00945fa382ab051651440826da7701533249b3a475",
"status": "CA",
"transaction_references": [
{"name": "tlid", "value": "0000000000000000000002"}
]
},
"status": "SUCCESS"
}
Payment with refund — /ws/query
{
"payment": {
"hash": "59acc5f00945fa382ab051651440826da7701533249b3a475",
"transaction_references": [
{"name": "tlid", "value": "0000000000000000000002"}
],
"refunds": [
{
"id": "1449603",
"transaction_references": [
{"name": "tlid", "value": "0000000000000000000002"}
]
}
]
},
"status": "SUCCESS"
}
Handling declines
When a Mastercard transaction is declined, EBANX still returns the TLID in the payment response if it was generated during the authorization attempt. This allows merchants to reference the TLID for reconciliation and dispute management, even for transactions that did not complete successfully.
The transaction_references array is included in the response when the TLID was generated and returned by the acquirer, regardless of the payment status (CO, CA, or PE). Merchants should persist the TLID from declined responses if they plan to resubmit the transaction or use the identifier for internal tracking.
The TLID is also included in notification callbacks for transactions where the identifier was generated, including declined transactions. Merchants receiving notifications can extract the TLID from the transaction_references array in the notification payload.
Impact on your integration
Merchants submitting an initial CIT do not need to include a TLID in the request — EBANX extracts and returns it when provided by the acquirer.
For applicable MITs, merchants must retain the TLID from the original CIT response and include it in each subsequent MIT request via the transaction_references field. This applies whether the original CIT was processed by EBANX or another PSP.
Automatic TLID handling by EBANX is limited to supported reversals and refunds linked to a known EBANX transaction. It does not extend to every MIT scenario.
The TLID applies to Mastercard 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.
