Mastercard Transaction Link ID (TLID)

Mastercard has introduced the Transaction Link Identifier (TLID), a 22-character identifier carried in DE 105 that is replacing legacy linking fields (Banknet Reference Number, Trace ID, Switch Serial Number). Mastercard expects the TLID from an original cardholder-initiated transaction (CIT) to be included on later merchant-initiated transactions (MITs) that reference it, for example a subscription sign-up (CIT) followed by a renewal charge (MIT) months later. Mastercard's published date for this is October 23, 2026. TLID applies to Mastercard transactions only.

Beyond CIT-to-MIT linking, Mastercard's TLID framework also covers refunds, voids, incremental authorizations and chargebacks. Where a gateway supports it, Spreedly carries the TLID forward on follow-up transactions that reference an earlier one, such as a capture, void or refund. Coverage varies by gateway, so check the Gateway support table below. Incremental authorizations and chargebacks are not part of Spreedly's current TLID support.

How Spreedly handles TLID

Spreedly captures the TLID returned on an original CIT and can attach it to the corresponding MIT automatically, as long as your integration follows the pattern below.

• Single subscription or installment plan per payment method: no action required. Spreedly links the CIT to its MITs using the payment method.
• Multiple subscriptions or installment plans on the same payment method: pass a customer_agreement_id with the CIT so Spreedly can tell which chain a given MIT belongs to. If you omit it in that scenario, the wrong TLID could be applied.
  • If you pass a customer_agreement_id Spreedly hasn't seen before, it is treated as the start of a new chain, the same as if you hadn't passed one.

TLID is returned on every transaction response from a gateway where capture is active (see Gateway support). You can also pass a TLID explicitly on a request if you want to manage it yourself.

How Spreedly decides which TLID to use

Every transaction is evaluated against the following logic, in order:

1. You pass tlid explicitly. Spreedly uses the value you provide, sends it to the gateway, and stores it for future lookups if you also passed a customer_agreement_id.
2. You pass customer_agreement_id and Spreedly has a stored TLID for it. Spreedly sends that TLID to the gateway. This is the normal renewal/MIT case.
3. You pass customer_agreement_id but Spreedly has no record of it. Treated as the start of a new chain: no TLID is sent, and what the gateway returns is stored against that customer_agreement_id.
4. You pass neither, but the transaction references an earlier one (a capture referencing its auth, a refund referencing its purchase). Spreedly carries the TLID forward from the referenced transaction.
5. None of the above apply. Treated as a new, unlinked transaction: no TLID is sent, and the gateway-returned TLID is stored against the payment method.

customer_agreement_id only matters when a single payment method has more than one active subscription or installment plan.

Examples

1. Receiving a TLID (first transaction in a chain | CIT)

When you run the initial authorization for a subscription or installment plan, pass customer_agreement_id so Spreedly can later tell which chain a follow-up MIT belongs to. Spreedly captures the tlid the gateway returns and includes it in the response.

Request POST /v1/gateways/{gateway_token}/purchase.json

{
  "transaction": {
    "payment_method_token": "AbC123examplePMtoken",
    "amount": 1999,
    "currency_code": "USD",
    "customer_agreement_id": "sub_9F2K-customer-example"
  }
}

Response

{
  "transaction": {
    "token": "XyZ789exampleTxnToken",
    "state": "succeeded",
    "customer_agreement_id": "sub_9F2K-customer-example",
    "tlid": "MC0001A2B3C4D5E6F7G8H9",
    "created_at": "2026-07-21T14:02:11Z"
  }
}

Spreedly retains the tlid, keyed to the payment method and customer_agreement_id, so you don't need to store it yourself.

2. Sending a TLID automatically (renewal | MIT)

For a later merchant-initiated transaction against the same agreement, pass customer_agreement_id again (or nothing, if there's only one active chain on that payment method). Spreedly looks up the stored tlid and attaches it before sending to the gateway.

Request

{
  "transaction": {
    "payment_method_token": "AbC123examplePMtoken",
    "amount": 1999,
    "currency_code": "USD",
    "customer_agreement_id": "sub_9F2K-customer-example"
  }
}

Response

{
  "transaction": {
    "token": "Qrs456exampleTxnToken",
    "state": "succeeded",
    "customer_agreement_id": "sub_9F2K-customer-example",
    "tlid": "MC0001A2B3C4D5E6F7G8H9",
    "created_at": "2026-10-24T09:15:47Z"
  }
}

Same tlid as the original CIT. Spreedly attached it for you.

3. Sending a TLID explicitly (self-managed)

If you want to override or manage TLID yourself, pass tlid directly on the request. Spreedly uses the supplied value instead of doing its own lookup, and still saves it for future use.

Request

{
  "transaction": {
    "payment_method_token": "AbC123examplePMtoken",
    "amount": 1999,
    "currency_code": "USD",
    "tlid": "MC0001A2B3C4D5E6F7G8H9"
  }
}

Response

{
  "transaction": {
    "token": "Tuv321exampleTxnToken",
    "state": "succeeded",
    "tlid": "MC0001A2B3C4D5E6F7G8H9",
    "created_at": "2026-10-24T09:16:03Z"
  }
}

Gateway support

TLID support depends on each gateway's ability to return and accept a TLID, so it is rolling out gateway by gateway. Each gateway has two separate capabilities:

• Capture: Spreedly reads the TLID from the gateway's response, returns it as tlid on the transaction, and stores it.
• Forwarding: Spreedly sends a stored or supplied TLID to the gateway on later transactions.

Each is one of: Active, Not implemented (Spreedly hasn't built it yet), or Not available from the gateway (the gateway doesn't expose a TLID field). The Details column lists the transaction types covered where forwarding is limited.

This table isn't exhaustive. Support is assessed on a rolling basis. If your gateway isn't listed, contact your Spreedly representative or contact customer support.