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 can also optionally send a TLID in the payment request via the transaction_references field to support use cases that require explicit transaction linking from the merchant side.
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.
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 — 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. |
Sending the TLID in a request
Merchants can optionally 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": 299.85,
"currency_code": "BRL",
"payment_type_code": "creditcard",
"transaction_references": [
{"name": "tlid", "value": "0000000000000000000002"}
]
}
}
The transaction_references field is optional in the request. When omitted, EBANX continues to handle TLID extraction and storage transparently from the acquirer's authorization response.
Response examples
When available, the TLID is returned inside the transaction_references array in the payment response. This applies to both successful and declined transactions. 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 present in the response 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
EBANX manages the full TLID lifecycle — extraction, persistence, and echoing — transparently. No mandatory 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.
Merchants who need explicit control over transaction linking can optionally send a TLID in the payment request via the transaction_references field. This is not required for standard payment flows — EBANX handles TLID assignment automatically when the merchant does not provide one.
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. Optionally, you can send a transaction_references array in the request to supply your own TLID for explicit transaction linking.
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.
