Mastercard Transaction Link ID (TLID)

Mastercard has recently introduced the Transaction Link Identifier (TLID), a 22-character identifier carried in DE 105 that replaces legacy linking fields (Banknet Reference Number, Trace ID, Switch Serial Number). Starting October 23, 2026, the TLID from an original cardholder-initiated transaction (CIT) should be included on later merchant-initiated transactions (MITs) that reference it, such as, a subscription sign-up (CIT) followed by a renewal charge (MIT) months later.

TLID also applies to voids, refunds, incremental authorizations, and chargebacks, but CIT-to-MIT linking for recurring billing and installment plans is the most immediate requirement for most Spreedly customers.

How Spreedly handles TLID

Spreedly captures the TLID returned on an original CIT and automatically attaches it to the corresponding MIT when it occurs so you don't need to build or maintain your own lookup logic.

• Single subscription or installment plan per payment method: no action required. Spreedly links the CIT to its MITs automatically 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 disambiguate which chain a given MIT belongs to. If this is omitted in that scenario, the wrong TLID could be applied to the transaction.
  • Note: If you pass a customer_agreement_id that Spreedly hasn't seen before, it's treated as the start of a new chain, the same as if you hadn't passed one at all.

TLID is returned on every transaction response from a supported gateway. You can also pass a TLID explicitly on a request if you want to manage it yourself.

Gateway support

TLID capture and forwarding is being rolled out gateway by gateway, since it depends on each gateway's ability to return and accept a third-party TLID. Check the table below for current status, or reach out to your Spreedly contact if your gateway isn't listed yet.

This table isn't exhaustive and gateway support is being assessed and added on a rolling basis. If your gateway isn't listed above, contact your Spreedly representative to check current status or contact customer support to make your request.

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 disambiguate which chain a follow-up MIT belongs to. Spreedly captures whatever tlid the gateway returns and includes it in the response with no extra work required.

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; therefore, 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 echoed it forward automatically.

3. Sending a TLID explicitly (self-managed)

If you want to override or manage TLID yourself, pass tlid directly on the request. When present, 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"
  }
}