Skip to content

Network Token

Introduction

Network token authorization allows merchants to process payments using pre-decrypted network token data from digital wallets (Apple Pay, Google Pay) or direct Token Service Provider (TSP) integrations. This payment method type is designed for merchants who handle wallet token decryption on their own infrastructure and need to pass the resulting DPAN, cryptogram, and ECI data through the gateway.

How It Works

sequenceDiagram
    participant Customer
    participant Merchant
    participant Gateway as Payment Gateway
    participant Acquirer

    Customer->>Merchant: Initiates payment (Apple Pay / Google Pay)
    Merchant->>Merchant: Decrypts wallet token (DPAN, cryptogram, ECI)
    Merchant->>Merchant: Encrypts sensitive fields with merchant public key
    Merchant->>Gateway: POST /api/transactions/authorize<br/>payment_method.type = "network-token"
    Gateway->>Gateway: Decrypts & validates DPAN (Luhn, brand)
    Gateway->>Gateway: Builds 3DS authorization from cryptogram + ECI
    Gateway->>Acquirer: Processes transaction
    Acquirer-->>Gateway: Authorization result
    Gateway-->>Merchant: Transaction response
    Merchant-->>Customer: Payment confirmation

Key Concepts

Device Primary Account Number (DPAN)

The DPAN is a tokenized card number issued by the card network (Visa, Mastercard, etc.) that substitutes the actual PAN. It is structurally similar to a card number (13–19 digits, passes Luhn validation) but is specific to the device and wallet.

Cryptogram

A payment cryptogram (also called TAVV — Token Authentication Verification Value) is a one-time-use value generated during the wallet authentication process. It proves that the transaction was authenticated by the cardholder's device.

  • Required for CRYPTOGRAM_3DS authentication (Apple Pay, Google Pay with full authentication)
  • Not present for PAN_ONLY tokens (Google Pay PAN_ONLY mode)

ECI (Electronic Commerce Indicator)

The ECI indicates the level of security used during authentication. It is required for CRYPTOGRAM_3DS flows and omitted for PAN_ONLY flows.

ECI Value Card Network Authentication Level
05 Visa, Amex, Discover, JCB Fully authenticated
02 Mastercard, Maestro Fully authenticated
06 Visa, Amex, Discover, JCB Attempted authentication
01 Mastercard, Maestro Attempted authentication
07 Visa, Amex, Discover, JCB No authentication
00 Mastercard, Maestro No authentication

Source

The source field identifies the origin of the network token. If omitted, it defaults to network-token.

Source Description
apple-pay Token from Apple Pay wallet
google-pay Token from Google Pay wallet
network-token Token from a direct TSP integration or other source (default)

Supported Card Brands

Network tokens are validated against the same card brands supported by your terminal configuration. The gateway determines the brand from the DPAN's BIN (first 6 digits) and validates it against the terminal's accepted card brands.

Data Fields

Field Encrypted Required Description
encrypted_token_number Yes Yes DPAN from the wallet/TSP
encrypted_expiration_month Yes Yes Token expiration month (1–12)
encrypted_expiration_year Yes Yes Token expiration year (4 digits, e.g. 2025)
encrypted_cryptogram Yes No Payment cryptogram (absent for PAN_ONLY)
eci No No Electronic Commerce Indicator — required for CRYPTOGRAM_3DS, omitted for PAN_ONLY. Valid values: 00, 01, 02, 05, 06, 07
source No No Token origin (apple-pay, google-pay, network-token). Defaults to network-token

Encryption

Encrypted fields must be encrypted using your merchant public key, the same key used for card payment encryption. See the Encryption Example for details.

No CVV

Network token transactions do not require a CVV. The cryptogram serves as the authentication proof instead.