⚠️
Mastercard Transaction Link Identifier (TLID)
Mastercard is introducing a new identifier, the Transaction Link Identifier (TLID), for Merchant Initiated Transactions (MITs). Mastercard has been returning this identifier since June 2, 2026, and merchants will be required to send it back on subsequent MITs starting October 23, 2026. dLocal will begin returning card.transaction_link_id ahead of that deadline [rollout date TBD].
What's changing: for Mastercard payments, dLocal will start returning a new field, card.transaction_link_id, in addition to the existing card.network_tx_reference. Starting October 23, 2026, card.transaction_link_id must be sent back on subsequent Mastercard MITs, alongside the existing card.network_payment_reference.

What stays the same: Visa payments are unaffected. Additionally, just like for Visa, the existing card.network_tx_reference and card.network_payment_reference fields will be maintained for the Mastercard Trace ID (the legacy Mastercard ID) as supplementary information until it is officially discontinued.

Merchants should start storing card.transaction_link_id from the initial CIT response once it becomes available, so the field is ready before the October deadline.

Categorize a transaction

Merchant Initiated Transactions (MIT) are payment transactions that are initiated by the merchant on behalf of the customer. In MITs, the merchant has control over the transaction and is authorized to charge the customer's account or credit card based on predefined terms and conditions agreed upon by the customer.

Payment examples:

Subscription payments. A customer signs up for a subscription service and the merchant is allowed to collect periodic payments to the customer's account.
Automatic renewals. In case a customer has opted for automatic renewals of services, the merchant can initiate the transaction without explicit customer approval.

Types of transactions

CIT: Customer Initiated Transactions

Payment transactions that are initiated by the customer.

For example, online purchases.

MIT: Merchant Initiated Transactions

Payment transactions that are initiated by the merchant and have already been approved by the customers to pay on their behalf.

For example, subscription payments or automatic renewals.

Create a MIT payment

Stored credentials

In order to indicate the type of transaction, use the parameters stored_credentials_type and stored_credentials_usage inside the Card Object.

Parameter	Type	Description	Mandatory?
`card.stored_credential_type`	String	Use this field to store credentials for future payments. Possible values: `CARD_ON_FILE` `SUBSCRIPTION` `UNSCHEDULED_CARD_ON_FILE` `INSTALLMENTS` `NO_SHOW` `DELAYED_CHARGES` `REAUTHORIZATION` `STANDING_ORDER`	Yes
`card.stored_credential_usage`	String	Indicates if this is the first time the token is used (an initial payment) or if the token has already been used for a previous payment (subsequent payment). Possible values: * `FIRST` * `USED`	Yes
`card.network_payment_reference`	String	This is the Network Transaction Reference you can find in the response to the first payment —to be sent for all subsequent Merchant Initiated Transactions (MIT).	Yes
`card.transaction_link_id`	String	Will be returned in the response to the first payment, and must be sent back for all subsequent Merchant Initiated Transactions (MIT) once available. Not applicable to Visa.	Not yet available. Available from dLocal starting [TBD]. Mandatory for Mastercard MITs starting October 23, 2026.

Network Transaction Reference

If the transaction is initiated by the customer (CIT), the network transaction reference will be found on the card.network_tx_reference field. These references are unique identifiers for each original authorization request.

Visa. The Visa Transaction Identifier (Transaction ID) is a numeric value up to 15 digits in length.
- Example of a Visa Transaction ID: 987654321234567
Mastercard. The Mastercard Trace ID is created from the Financial Network Code, Banknet Reference Number, and Banknet Settlement Date.
- Example of a Mastercard Trace ID: MCCABC1XY0101
Mastercard TLID. dLocal will start returning this additional identifier, the Transaction Link Identifier (TLID), in card.transaction_link_id ahead of the October 23, 2026 deadline, when merchants must begin sending it back on Mastercard MITs.
- Example of a Mastercard TLID: Z0fE_2qV-3pWft4vHt7Ki6M

Stored credential type

Type	Description
`CARD_ON_FILE`	Allow customers one-click payment or a smooth checkout process.
`SUBSCRIPTION`	Transactions are processed at a fixed, regular interval to which the user has given consent.
`UNSCHEDULED_CARD_ON_FILE`	Transaction that occurs in a non-fixed time.
`INSTALLMENTS`	Agreement with the customer to initiate one or more future transactions over a period for a single purchase.
`NO_SHOW`	Penalty fee charged to the customer when the terms of an agreement are not met.
`DELAYED_CHARGES`	Additional charge associated with an agreement between customer and merchant for services provided.
`REAUTHORIZATION`	Extend an expired authorization.
`RESUBMISSION`	Valid when an authorization could not be performed due to insufficient funds and a cardholder-initiated purchase already occurred
`STANDING_ORDER`	Consumer agrees to store the credential-on-file and initiates the first transaction in a series intended to be for a variable amount and a fixed frequency.

Examples

Visa MIT

curl -X POST \
   -H 'X-Date: 2018-02-20T15:44:42.310Z' \
   -H 'X-Login: {x-login}' \
   -H 'X-Trans-Key: {x-trans-key}' \
   -H 'Content-Type: application/json' \
   -H 'X-Version: 2.1' \
   -H 'User-Agent: MerchantTest / 1.0 ' \
   -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1...' \
   -d '{body}'
   https://api.dlocal.com/secure_payments

{
    "amount": 120.00,
    "currency" : "USD",
    "country": "BR",
    "payment_method_id" : "CARD",
    "payment_method_flow" : "DIRECT",
    "payer":{
        "name" : "John Doe",
        "email" : "[email protected]",
        "document" : "53033315550",
        "phone": "9908734801"
    },
    "card":{
        "holder_name" : "John Doe",
        "number" : "4111111111111111",
        "cvv" : "123",
        "expiration_month" : 10,
        "expiration_year" : 2040,
        "stored_credential_type": "SUBSCRIPTION",
        "stored_credential_usage": "USED",
        "network_payment_reference": "987654321234567"
    },
   "order_id": "387ac7f5-9cbf-462e-ae41-971638788ccc",
   "notification_url": "http://merchant.com/notifications"
}

curl -X POST \
   -H 'X-Date: 2018-02-20T15:44:42.310Z' \
   -H 'X-Login: {x-login}' \
   -H 'X-Trans-Key: {x-trans-key}' \
   -H 'Content-Type: application/json' \
   -H 'X-Version: 2.1' \
   -H 'User-Agent: MerchantTest / 1.0 ' \
   -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1...' \
   -d '{body}'
   https://api.dlocal.com/secure_payments

{
    "amount": 120.00,
    "currency" : "USD",
    "country": "BR",
    "payment_method_id" : "CARD",
    "payment_method_flow" : "DIRECT",
    "payer":{
        "name" : "John Doe",
        "email" : "[email protected]",
        "document" : "53033315550",
        "phone": "9908734801"
    },
    "card":{
      "holder_name" : "John Doe",
      "last4": "1111",
      "expiration_month" : 10,
      "expiration_year" : 2040,
      "network_payment_reference": "987654321234567"
    },
   "order_id": "387ac7f5-9cbf-462e-ae41-971638788ccc",
   "notification_url": "http://merchant.com/notifications"
}

Mastercard MIT with Transaction Link ID

The following example shows a Mastercard MIT once transaction_link_id is available. See the callout above for the rollout timeline.

curl -X POST \
   -H 'X-Date: 2018-02-20T15:44:42.310Z' \
   -H 'X-Login: {x-login}' \
   -H 'X-Trans-Key: {x-trans-key}' \
   -H 'Content-Type: application/json' \
   -H 'X-Version: 2.1' \
   -H 'User-Agent: MerchantTest / 1.0 ' \
   -H 'Authorization: V2-HMAC-SHA256, Signature: 1bd227f9d892a7f4581b998c21e353b1...' \
   -d '{body}'
   https://api.dlocal.com/secure_payments
{
    "amount": 120.00,
    "currency" : "USD",
    "country": "BR",
    "payment_method_id" : "CARD",
    "payment_method_flow" : "DIRECT",
    "payer":{
        "name" : "John Doe",
        "email" : "[email protected]",
        "document" : "53033315550",
        "phone": "9908734801"
    },
    "card":{
        "holder_name" : "John Doe",
        "number" : "5111111111111111",
        "cvv" : "123",
        "expiration_month" : 10,
        "expiration_year" : 2040,
        "stored_credential_type": "SUBSCRIPTION",
        "stored_credential_usage": "USED",
        "network_payment_reference": "MCCABC1XY0101",
        "transaction_link_id": "Z0fE_2qV-3pWft4vHt7Ki6M"
    },
   "order_id": "387ac7f5-9cbf-462e-ae41-971638788ccd",
   "notification_url": "http://merchant.com/notifications"
}

{
    "id": "T-4-704f49ba-46e9-49a3-81c6-beac52cba6d8",
    "amount": 120,
    "currency": "USD",
    "payment_method_id": "CARD",
    "payment_method_type": "CARD",
    "payment_method_flow": "DIRECT",
    "country": "BR",
    "card": {
        "holder_name": "John Doe",
        "expiration_month": 10,
        "expiration_year": 2040,
        "last4": "1111",
        "network_tx_reference": "MCCABC1XY0101",
        "transaction_link_id": "Z0fE_2qV-3pWft4vHt7Ki6M"
    },
    "created_date": "2026-07-03T17:13:48.000+0000",
    "status": "PAID",
    "status_detail": "The payment was paid.",
    "status_code": "200",
    "order_id": "387ac7f5-9cbf-462e-ae41-971638788ccd",
    "notification_url": "http://merchantsite.com/notifications"
}

📘
API Reference
For more detail information on how to make a payment, check the API Reference section.

Mastercard Transaction Link Identifier (TLID)

Categorize a transaction

Types of transactions

CIT: Customer Initiated Transactions

MIT: Merchant Initiated Transactions

Create a MIT payment

Stored credentials

Network Transaction Reference

Stored credential type

Examples Visa MIT

Mastercard MIT with Transaction Link ID

API Reference

Examples

Visa MIT