HomeGuidesAPI ReferenceStatus Page
Guides

Network tokens

Learn how to handle network token payments.

Suggest Edits

Network tokens are digital representations of sensitive payment card data, such as credit card numbers, issued by payment networks like Visa, Mastercard, or American Express.

These tokens replace actual card data during transactions, enhancing security by reducing exposure to potential fraud.

Implementation options

dLocal token management

dLocal handles network tokenization automatically, requiring no additional integration. dLocal requests and replaces card details with a network token before processing, based on brand and country capabilities.

Third-Party token management

Network tokens are requested and managed through a third party, with each payment request requiring the token to be obtained and included manually.

Network token in recurring payments

Third-Party token management

How it works?

To process recurring payments using network tokens, follow these steps:

  • Step 1: Make an initial network token payment. To initiate recurring payments with network tokens, the first transaction must include both a cryptogram and a Customer-Initiated Transaction (CIT) indicator. This ensures the payment is authorized and linked to the customer's consent.
  • Step 2: Make a subsequent network token payment. For subsequent payments, the transaction should include Merchant-Initiated Transaction (MIT) values. In these cases, the cryptogram is optional, as the merchant initiates the payment without direct customer involvement.

Step 1: Make an initial network token payment

CIT (Customer Initiated Transactions)

The first payment can be a one-time transaction, the initial payment of a subscription, or the first payment in a recurring agreement.

To process this payment, you must send the network token along with the required CIT fields:

  • card.cryptogram (mandatory)
  • card.stored_credential_usage (must be set to FIRST)
  • card.stored_credential_type (should match the recurring payment type that best fits your use case)

Since this is the first payment in a recurring agreement, card.stored_credential_usage must be set to FIRST. The value for card.stored_credential_type should correspond to the appropriate recurring payment type.

For more details on the available stored credential types, refer to the Merchant Initiated Transactions page.


Main request fields

These fields should be added to the Card Object request for sending payments with network tokens.

PropertyRequired?TypeDescription
card.network_tokenRequiredStringNetwork Token DPAN (Device Primary Account Number).
card.holder_nameRequiredStringCardholder's full name.
card.expiration_monthRequiredIntegerA two-digit number representing the Network Token expiration month.
card.expiration_yearRequiredIntegerA four-digit number representing the Network Token expiration year.
card.cryptogramRequiredStringThe unique cryptogram generated by the issuer for the network token in use in the transaction.

Example request

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/payments

{
    "amount": 120.00,
    "currency": "USD",
    "country": "BR",
    "payment_method_id": "CARD",
    "payment_method_flow": "DIRECT",
    "payer":{
        "name" : "Thiago Gabriel",
        "email" : "thiago@example.com",
        "document" : "53033315550"
    },
    "card":{
       "holder_name": "Thiago Gabriel",
        "network_token": "4111111111111111",
        "cryptogram": "CCADBxYzRTBBXXXXXXXYZa0AbZD=",
        "expiration_month": 10,
        "expiration_year": 2040,
        "stored_credential_type": "SUBSCRIPTION",
        "stored_credential_usage": "FIRST"
    },
   "order_id": "387ac7f5-9cbf-462e-ae41-971638788ccc",
   "notification_url": "http://merchantsite.com/notifications"
}

{
    "id": "D-4-e2227981-8ec8-48fd-8e9a-19fedb08d73a",
    "amount": 120,
    "currency": "USD",
    "payment_method_id": "CARD",
    "payment_method_type": "CARD",
    "payment_method_flow": "DIRECT",
    "country": "BR",
    "card": {
        "holder_name": "Thiago Gabriel",
        "expiration_month": 10,
        "expiration_year": 2040,
        "brand": "VI",
        "last4": "1111",
        "network_tx_reference": "MCC000000355"
    },
    "created_date": "2019-02-06T21:04:43.000+0000",
    "approved_date": "2019-02-06T21:04:44.000+0000",
    "status": "PAID",
    "status_detail": "The payment was paid",
    "status_code": "200",
    "order_id": "657434343",
    "notification_url": "http://merchantsite.com/notifications"
}

📘

Store the Network Transaction Reference

It’s important to store the Network Transaction Reference, found in the card.network_tx_reference field in the response.

This reference corresponds to: Transaction ID (Visa) or TraceID (Mastercard). You must include this reference in subsequent payment requests to link them to the initial payment.

You can skip this step if you have already made the initial payment using the CIT parameters.


Step 2: Make a subsequent network token payment

MIT (Merchant Initiated Transactions)

Once the initial network token payment has been completed with a cryptogram as part of a recurring agreement, you can process subsequent payments using the same network token and expiration date—without requiring a cryptogram.

To do this, you must send the network token along with the required MIT fields:

  • card.cryptogram (optional; can be omitted)
  • card.stored_credential_usage (must be set to USED)
  • card.stored_credential_type (must match the type used in the initial network token payment)
  • card.network_payment_reference (must contain the card.network_tx_reference from the initial CIT payment)

Since this payment is part of a recurring agreement, card.stored_credential_usage should be set to USED, and card.stored_credential_type must remain the same as in the initial CIT transaction. Additionally, card.network_payment_reference should match the card.network_tx_reference received from the first payment.


Example request

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/payments

{
    "amount": 120.00,
    "currency": "USD",
    "country": "BR",
    "payment_method_id": "CARD",
    "payment_method_flow": "DIRECT",
    "payer":{
        "name" : "Thiago Gabriel",
        "email" : "thiago@example.com",
        "document" : "53033315550"
    },
    "card":{
       "holder_name": "Thiago Gabriel",
        "network_token": "4111111111111111",
        "expiration_month": 10,
        "expiration_year": 2040,
        "stored_credential_type": "SUBSCRIPTION",
        "stored_credential_usage": "USED",
        "network_payment_reference": "MCC000000355"
    },
   "order_id": "387ac7f5-9cbf-462e-ae41-971638700abc",
   "notification_url": "http://merchantsite.com/notifications"
}

{
    "id": "D-4-e2227981-8ec8-48fd-8e9a-19fedb08d73g",
    "amount": 120,
    "currency": "USD",
    "payment_method_id": "CARD",
    "payment_method_type": "CARD",
    "payment_method_flow": "DIRECT",
    "country": "BR",
    "card": {
        "holder_name": "Thiago Gabriel",
        "expiration_month": 10,
        "expiration_year": 2040,
        "brand": "VI",
        "last4": "1111",
        "network_tx_reference": "MCC000000355"
    },
    "created_date": "2019-02-06T21:04:43.000+0000",
    "approved_date": "2019-02-06T21:04:44.000+0000",
    "status": "PAID",
    "status_detail": "The payment was paid",
    "status_code": "200",
    "order_id": "657434343",
    "notification_url": "http://merchantsite.com/notifications"
}

🚧

Consistent amount for subsequent payments

If the initial network token payment with a cryptogram was processed as a CIT SUBSCRIPTION, all subsequent network token payments without a cryptogram must be processed as MIT SUBSCRIPTION with the same amount. Otherwise, the transaction will be rejected.

Updated 1 day ago

© 2024 DLOCAL. ALL RIGHTS RESERVED

Dlocal LLP (Company Number UK OC413287) is a limited liability partnership incorporated in England and Wales. DLocal Limited (Company Registration Number C77538) is authorised by the Malta Financial Services Authority under the Financial Institutions Act for the issuance of electronic money and the provision of payment services. Dlocal Corp LLP (Company Number UK OC 424987) is registered as a Money Service Business (MSB) with Financial Crime Enforcement Network in United States of America (USA) under MSB Registration Numbers 31000193620515. Dlocal Corp LLP acts as agent of e-commerce merchants based in the USA, and collects payments from end users based in emerging markets, on behalf of the merchants.