Network Token

Overview

In the context of card payments, network tokens are secure, digital substitutes for a customer's actual credit or debit card number, also known as the Primary Account Number (PAN). They're created and managed by card networks like Visa, Mastercard, and American Express, acting as a proxy for the real card data. Network tokens are unique to a specific combination of a card, a merchant, and a payment processor, making them useless if stolen from a merchant's system.

Network Tokens and Card Numbers

Network tokens are designed to be similar to card numbers in how they function within the payment process. Like a regular card number, a network token is a string of digits used to identify the customer's account for a transaction. However, unlike a PAN, a token:

• Has no value outside its intended use. If a token is stolen from a merchant, it can't be used by a fraudster at a different merchant or for any other purpose, significantly reducing the risk of a data breach.
• Updates automatically. If a customer's card expires or is replaced, the network token is automatically updated by the card network, so merchants don't have to request new card details from the customer for recurring payments.

The Required Cryptogram

A cryptogram is a dynamic, single-use, cryptographic value that acts as a security measure for a network token transaction. Think of it as a transaction-specific CVV. For every transaction initiated using a network token, a new cryptogram is generated and sent along with the token to the card network. The card network then validates the cryptogram to ensure the token is being used legitimately for that specific payment. This extra layer of security helps prevent fraudulent use of a token, even if it's been intercepted.

How Merchants Can Use Network Tokens

Merchants who have a token services provider that supports network tokens can streamline their payment process and enhance security. When creating a transaction, instead of sending the sensitive PAN, they can send the network token in the number field and the cryptogram as a separate field within the card object in the API request. The merchant's payment service provider then forwards this information to the card network to authorize and process the payment. This approach helps reduce the merchant's burden of handling and storing sensitive card data, lowers their risk of a data breach, and can lead to higher authorization rates.

Features

Enhanced Security and Reduced Fraud: Network tokens replace sensitive card numbers, meaning merchants don't have to handle or store the actual PAN. If a token is compromised, it's useless to a fraudster because it's tied to a specific merchant and a single-use cryptogram is required for each transaction. This significantly reduces the risk of data breaches and the associated costs.

Higher Authorization Rates: Because network tokens are issued and managed by the card networks themselves, they are seen as highly secure and trustworthy. This often leads to higher transaction approval rates, as card issuers are more confident in approving tokenized payments.

Seamless Card Updates: Network tokens are automatically updated by the card networks when a customer's physical card expires, is lost, or is re-issued. For merchants, especially those with subscription or recurring billing models, this eliminates the problem of "involuntary churn" caused by failed payments due to outdated card details.

Lower PCI Compliance Burden: By not storing or handling sensitive card data, a merchant's Payment Card Industry Data Security Standard (PCI DSS) compliance scope can be significantly reduced, simplifying the compliance process and lowering the associated costs.

Improved Customer Experience: Customers don't have to manually update their card information for recurring payments or saved card-on-file transactions. This creates a smoother, more convenient checkout experience and reduces friction.

Payment Flow

Request Payload

{
    "contract_id": "MY_CONTRACT_ID",
    "reference_id": "MY_REFERENCE_ID",
    "notification_url": "https://my.notification.url/callback/",
    "ip_address": "0.0.0.0",
    "payment": {
        "method": "CREDITCARD",
        "amount": 123.45,
        "asset": "BRL",
        "soft_descriptor": "SOFT_DESCRIPTOR",
        "delay_capture": true,
        "save_card": false,
        "currency": "BRL",
        "country": "BR",
        "card": {
            "number": "2223000250000004",
            "holder": "Alice Sonnentag",
            "cvv": "123",
            "year": 2026,
            "month": 12,
            "cryptogram": "ANbuvvxnDbK2AAEShHMWGgADFA==",
            "installments": 1
        }
    },
    "person": {
        "full_name": "Alice Sonnentag",
        "email": "[email protected]",
        "tax_id": "39784045087",
        "birth_date": "1978-08-21"
    },
    "disable_address": false,
    "address": {
        "main": "Rua Araguari",
        "number": "817",
        "additional": "Apto 54",
        "locality": "Vila Sônia",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR",
        "zip_code": "04514-041"
    },
    "extra_data": {
        "my-conciliation-number": "xxxxxx"
    }
}

Field Descriptions

Main Fields

• contract_id (string): Identifier of the contract associated with the payment.
• reference_id (string): Unique reference identifier for transaction tracking.
• notification_url (string): URL for sending notifications about payment status.
• ip_address (string): IP address of the customer making the payment.

payment Object

• method (string): Payment method used. Example: "CREDITCARD".
• amount (number): Transaction amount.
• asset (string): Transaction currency (example: "BRL").
• soft_descriptor (string): Name appearing on the credit card statement.
• delay_capture (boolean): Indicates if payment capture will be delayed.
• save_card (boolean): Indicates if the card will be saved for future transactions.
• currency (string): Currency used.
• country (string): Transaction country.

card Object

• number (string): Network Token number.
• holder (string): Cardholder's name.
• cvv (string): Card security code.
• year (number): Card expiration year.
• month (number): Card expiration month.
• cryptogram (string): Cryptogram string.
• installments (number): Number of installments.

person Object

• full_name (string): Payer's full name.
• email (string): Payer's email.
• tax_id (string): Payer's tax ID (CPF or CNPJ).
• birth_date (string): Date of birth in "YYYY-MM-DD" format.

address Object

• main (string): Street name.
• number (string): House/building number.
• additional (string): Address complement.
• locality (string): Neighborhood.
• city (string): City.
• state (string): State.
• country (string): Country.
• zip_code (string): ZIP code.

extra_data Object

Additional data related to the transaction.

Considerations

• Ensure to use real and secure data in the implementation.
• The notification URL must be prepared to receive POST calls with transaction status updates.
• Additional features such as 3DS authentication and tokenization are covered in separate documentation.

Example Response

{
    "transaction_id": "TRANSACTION_12345",
    "status": "AUTHORIZED",
    "authorization_code": "AUTH_67890",
    "payment_url": "https://payment.gateway/redirect"
}

This documentation provides an overview of how to integrate credit card payments using this API.