Network Tokens

Network tokens are tokens generated through tokenization services offered by the card networks (such as Visa and Mastercard).

Network tokens are merchant-specific token values (16-digits) generated by the large card companies (e.g., Visa and Mastercard) and are designed to represent and replace a shopper’s card information in various transactions where a card needs to be saved. Using Network Tokens is excellent in strengthening shoppers' identities, protecting underlying account information, and helping combat and mitigate fraud.

HUB Tokens vs. Network Tokens

Similar to HUB tokens, Network tokens allow payments to be processed without exposing the shopper’s card details. Note that the adoption of network tokens does not affect your payment processing e.g., authorization, clearing, settlement, and exception processing, but is added atop of the regular tokenization process. Learn more on how to collect customer card information.

Why You Should Adopt Network Tokens

Network Tokens are especially designed for transactions that are part of a Card-on-File business model. These include recurring, one-click, or similar transactions where card details need to be saved for future uses. You may also opt to use network tokens given their additional benefits:

Increased payment security, given that network tokens are protected with a cryptogram and are also merchant-specific.
Higher approval rates than payments made without network tokens, reducing ‘Expired Cards’ and ‘Lost Stolen’ type declines.
Better shopper experience— Shoppers remain informed regarding their stored card information and can ask their card issuer to deactivate or delete a token.
Shoppers see the card’s latest brand visuals in your checkout page, e.g. an updated card logo after changing card plans.
The ability to efficiently manage a token’s status and deactivate (suspend) and re-activate it if needed.
Compliance with EMVCo’s network token standards with minimal integration efforts.

Getting Started

You must first register for our Network Token Service to use network tokens. To do so, you should submit your request to our Customer Experience department department, which will enable the service for you.

Using PayU’s Network Token Service

PayU currently offers two ways to provision Network Tokens — via either an Embedded or Designated (Advanced) flows. Both flows serve the same purpose of provisioning network token for a specific customer card number, but they differ in the token data you receive back, including detailed errors. The Designated flow (which is richer in data) is also mandatory for merchants operating in India and is compliant with the Reserve Bank of India (RBI) regulations (more on this topic in the following sections).

It’s worth noting that you do not communicate directly with the card network’s tokenization service to request a token. Instead, we provisions (request) the token on your behalf. We’ll dive into the details of using network tokens in the sections that follow.

More on Tokenization

We assume you are already familiar with the procedures for collecting and tokenizing a user’s card information. If not, we recommend you to explore this topic before reading on.

The Embedded flow

The embedded Network Token provisioning flow is our ‘under-the-hood’ option for provisioning network tokens. The flow is activated after you create a HUB token and request for service activation (see Registering for PayU’s Network Token Service). This flow is seamless and suitable for all merchants. Still, European merchants are especially encouraged to use this service as they benefit from reduced interchange fees from Visa and Mastercard.

The Designated flow

In the Designated flow, Network Tokens are provisioned via the Create Payment Method with Network Token API. This flow provides enhanced token data, e.g., error mapping, in case of a provisioning-failure, so the merchant can initiate a customer recovery flow, if necessary. This flow is mandatory for merchants operating in India with a ‘card-on-file’ business case as it enables customer card number deletion after successful token provisioning. Thanks to a designated API, this flow also provides better flexibility and control over a network token’s status.

Getting More Information about your Network Token

Suppose you wish to get more information about the Network Token associated with the token that was saved in a customer object, including its status, provider_name etc., you can call either the Retrieve a Payment Method or the Retrieve all Payment Methods requests. You will receive the corresponding information about the network token in the network_token object. The information in the network token object will depend on whether you use the Embedded or the Designated flow.

Embedded flow network_token object:

...
{
    "network_token": { 

      "provider_name": "visa", 
      "status": "ACTIVE", 
      "data": { 
          "created_timestamp": 1587402701891, 
          "modified_timestamp": 1587402701891, 
          "reference_id": "07baf4d3-4517-4c13-a4ac-965dd62ac5df", 
          "payment_account_reference": "429f614e-9754-45ed-9f8d-944890f6939c", 
          "additional_details": {}, 
          "network_token_bin_number": "string" 
          }, 
      "last_4_digits": "string" 
    } 
}
...

Designated flow network_token object:

...
{
 "network_token": {
    "provider_name": "visa",
    "status": "ACTIVE",
    "created_timestamp": "string",
    "modified_timestamp": "string",
    "reference_id": "string",
    "payment_account_reference": "string",
    "expiration_date": "10/2025",
    "additional_details": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "card_network_token": "string",
    "network_token_bin_number": "string",
    "card_media": [
      {
        "encoded_data": "string",
        "media_type": "logo",
        "mime_type": "image/png",
        "width": "string",
        "height": "string"
      }
    ]
 }
}
...

Fetching Card Media

If you want to fetch card media data, so that you can show a logo of the card in your checkout page, then call the Retrieve all Payment Methods request with the get_card_media=all query parameter:

https://api.paymentsos.com/customers/{customer_id}/payment-methods?get_card_media=all

The card media will be returned in the network.token.card_media array. Here’s an example:

...
{
  "network_token": {
  
  },
  "card_media": [
        {
          "encoded_data": "iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAIAAAD...",
          "media_type": "logo",
          "mime_type": "image/png",
          "width": "100",
          "height": "100"
        },
        {
          "encoded_data": "JVBERi0xLjYNJeLjz9MNCjcgMCBvYmoN...",
          "media_type": "digital_card_art",
          "mime_type": "image/pdf"
        }
      ]
}
...

Processing Network Tokens Provisioned by PayU

Network tokens provisioned by PayU can only be used in transactions processed with stored card credentials, so you first need to follow the steps in Reusing Card Information to store your customers' card details. As part of the flow, you will generate and store a HUB token that represents the user’s card information. The moment you save that token, we will provision (request) a network token on your behalf.

Note that Network Tokens are not returned directly to you, but are saved by us. You simply need to pass the HUB token in the Create Authorization or Create Charge requests and we make sure that the network token is used instead. You can validate this, by checking the network_token_usage object returned in the response of the Create Authorization or Create Charge requests. Here’s an example:

...
{
  "network_token_usage": {
    "cryptogram_type": "TAVV",
    "is_used": true
  }
}
...

Processing Network Token Requested by a Third-Party Token Provider

If desired, you can also use a network token you obtained from a third-party token provider (or directly from the card schemes). To do so, pass a payment_method.source_type of network_token and a payment_method.type of untokenized when invoking a Create Authorization or Create Charge requests. In the payment_method.card_number field, pass the network token. Using a network token in this flow also requires passing the network_token_sca_data.cryptogram value you received from the provider. Here’s an example:

...
{
"payment_method": {
    "source_type": "network_token",
    "type": "untokenized",
    "expiration_date": "22-2030",
    "card_number": "4242424242424242"
  },
"network_token_sca_data": {
  "cryptogram": "US20170163629A1"
  }
}
...

Network Tokens Requested by ApplePay

The use of ApplePay network tokens depends on a provider’s support of this functionality, and whether they enable the decrypted or non-decrypted payload flows. Head over to finding a provider and choose ‘eWallet’ from the drop-down menu to filter. Choose your provider from the filtered list and navigate to the Integration Procedures > Integrating Apple Pay section for a step-by-step guide.

ApplePay Decrypted Token Flow

In the decrypted token flow, you must decrypt the payload to extract the network token you’ve received from Apple — and then pass it to PaymentsOS in the Create Authorization or Create Charge requests.

ApplePay Non-Decrypted Token Flow

When a provider supports the non-decrypted token flow, you can pass the token ‘as is’ (without decryption), and the provider will then extract the network token for you.

Managing and Understanding Network Token Statuses

Network Tokens can receive the following statuses (regardless of the type of flow used):

Suspended

Active

Pending

Deleted

One of the advantages of using network tokens is that you can easily manage their status. For example, you can suspend a token and then reactivate it at a later stage. To manage the status of a network token, use one of the following API requests:

Suspend a Token: Deactivate a network token, for the specified customer and HUB token.
Resume a Token: Resume a network token, for the specified customer and HUB token.
Delete a Network Token : Delete a network token.

Suppose you’d like to see the status of the network token that was provisioned, including additional information. In that case, you can do so in the response of the tokenization request that you invoked while tokenizing a user’s card information, or in the response of the Create a Payment Method request. Information about the token is returned in the network_token object:

...
{
  "network_token": {
    "provider_name": "visa",
    "status": "ACTIVE",
    "data": {
      "reference_id": "a6783d653258258098441850237b6602",
      "created_timestamp": 1596475582848,
      "modified_timestamp": 1596475582848,
      "payment_account_reference": "V0010013020057607176303215146",
      "additional_details": {
        "enrollment_id": "d3c9470960eb985de222186f64b10b02"
      },
      "last_4_digits": "XXXXX"
    }
  }
}
...

Status Changes Requested by Card Issuer

A shopper may ask their card issuer to suspend or remove a token. In this case, the card network will notify PaymentsOS, after which the token will be deleted or deactivated in accordance with the request. You can create a [Webhook]((../development-tools/webhooks.html#creating-webhooks) event to be notified of such changes.

Network Token Webhook Events

If desired, you can create a webhook notification for when a network token is created or changes its status. To do so, follow the instructions on how to create Webhooks configurations and enable the Create or Update event for Payment Method alert.

The following is an example of the webhook body received for a Payment Method (Network Token) alert:

{
  "id": "string",
  "type": "tokenized",
  "token_type": "credit_card",
  "created": 1587402701891,
  "modified": 1587402701891,
  "holder_name": "string",
  "href": "string",
  "customer": "string",
  "additional_details": {
    "property1": "string",
    "property2": "string"
    },
  "shipping_address": {
    "country": "USA",
    "state": "TX",
    "city": "Greenville",
    "line1": "10705 Old Mill Rd",
    "line2": "11605 Young Mill Rd",
    "zip_code": "75402-3435",
    "title": "Dr.",
    "first_name": "John",
    "last_name": "Travolta",
    "phone": 13301303330,
    "email": "john.travolta@johntravolta.com"
    },
  "billing_address": {
    "country": "USA",
    "state": "TX",
    "city": "Greenville",
    "line1": "10705 Old Mill Rd",
    "line2": "11605 Young Mill Rd",
    "zip_code": "75402-3435",
    "title": "Dr.",
    "first_name": "John",
    "last_name": "Travolta",
    "phone": 13301303330,
    "email": "john.travolta@johntravolta.com"
    },
  "card": {
    "status": "ACTIVE",
    "expiration_date": "string",
    "last_4_digits": "string",
    "bin_number": "string",
    "pass_luhn_validation": true,
    "fingerprint": "string",
    "bin_details": {}
    },
  "network_token": {
    "provider_name": "visa",
    "created": 1587402701891,
    "modified": 1587402701891,
    "reference_id": "07baf4d3-4517-4c13-a4ac-965dd62ac5df",
    "payment_account_reference": "429f614e-9754-45ed-9f8d-944890f6939c",
    "expiration_date": "10/2025",
    "additional_details": {},
    "network_token_bin_number": "string",
    "last_4_digits": "string"
    }
}

Last modified August 28, 2022