Transaction Link Identifier (TLID)

Overview

The Transaction Link Identifier (TLID) is a Mastercard mandate for stored credential payments. Mastercard generates a TLID on the cardholder-initiated transaction (CIT) that sets up a stored credential agreement. Every later merchant-initiated transaction (MIT) in that agreement must carry the same TLID, so the issuer can link it back to the original authenticated payment.

TLID runs alongside Scheme Reference Data (SRD). It doesn't replace SRD yet, so both are sent on Mastercard MITs until Mastercard announces a date to retire SRD.

Do I need to take action?

A TLID is generated by Mastercard, not by Acquired or the acquirer. This means a TLID from a CIT processed by another provider is valid on an MIT processed by Acquired, and the other way round.

Where the TLID appears

transaction_link_id is returned in the response to these endpoints:

• /payments, /payments/reuse, /payments/recurring, /payments/apple-pay and /payments/google-pay
• /psp-payments, /psp-payments/reuse, /psp-payments/recurring, /psp-payments/apple-pay and /psp-payments/google-pay
• GET /transactions/{transaction_id} and GET /transactions

The value is null when no TLID is available, for example on a Visa payment or where the acquirer didn't return one.

{
  "transaction_id": "a7e3fde5-5b83-44f4-9915-782bc7121717",
  "status": "success",
  "issuer_response_code": "00",
  "card_id": "00cfdbdc-5e81-4ce2-adc1-14920120618f",
  "scheme_reference_data": "MCC4KGZ7HTQ2X",
  "transaction_link_id": "ex9D-Gm0NN9Gaih0zZ0s99",
  "links": [
    {
      "rel": "self",
      "href": "/v1/transactions/a7e3fde5-5b83-44f4-9915-782bc7121717"
    }
  ]
}

Mastercard TLIDs are 22 characters long and can contain letters, numbers, hyphens and underscores. Store the value exactly as returned.

How Acquired manages the TLID

Stored cards (card_id)

• When you create a card with create_card: true, we store the TLID returned on that payment against the card_id.
• When you send a /payments/recurring request with a card_id, we send the stored TLID to the acquirer.
• A recurring payment doesn't replace the TLID already stored against the card_id, because the TLID belongs to the original agreement.
• A new CIT on the same card_id through /payments/reuse replaces the stored TLID with the one returned on that payment. If Mastercard doesn't return a new TLID, the response contains the TLID already stored against the card_id.

External recurring (/psp-payments/recurring)

Send the TLID in payment.transaction_link_id:

{
  "transaction": {
    "order_id": "1f1f2a61-5b68-4725-a0ce-9560514ec00b",
    "amount": 15.02,
    "currency": "GBP",
    "capture": true
  },
  "payment": {
    "card": {
      "holder_name": "E Johnson",
      "number": "5555555555554444",
      "expiry_month": 10,
      "expiry_year": 28
    },
    "scheme_reference_data": "MCC4KGZ7HTQ2X",
    "transaction_link_id": "ex9D-Gm0NN9Gaih0zZ0s99",
    "subscription_reason": "recurring"
  }
}

The field is optional and accepts up to 36 characters. If you also send create_card: true, we store the TLID you send against the new card_id. If you don't send one, we store the TLID returned by the acquirer.

For more on external recurring, see the PSP API Guide.

If you don't have a TLID for an agreement

Agreements set up before Mastercard started generating TLIDs, or where the TLID wasn't stored, won't have one. Mastercard allows two ways to get a TLID for these agreements:

1. Process a new CIT with the cardholder. The TLID returned on that payment is used for the agreement from then on.
2. Use the TLID from an undisputed MIT in the same agreement that was processed at least three months before the current payment. Mastercard treats this as a fallback only.

If you vault cards yourself, you need to apply these rules before sending the MIT.