Network Tokens

What you should already know

We assume you have already familiarized yourself with the procedures for collecting and tokenizing a user's card information. If not, we recommend you first review the topic explaining how to collect a user's card information before reading on.

Network tokens are tokens generated through tokenization services offered by the card networks (such as Visa and Mastercard). Network tokens are similar to tokens generated by PaymentsOS, in that they also allow payments to be processed without exposing a shopper's actual card details. You may, however, choose to use network tokens given their additional advantages:

  • Increased payment security, as network tokens are protected with a cryptogram.

  • Higher approval rates compared to payments made without network tokens.

  • Better shopper experience. Shoppers always have insight into where their card information is stored and can ask the card issuer to deactivate or delete a token. Shoppers will also always see a card's latest brand visuals in your checkout page, such as an updated logo after changing card plans.

  • The ability to easily manage a token's status and deactivate (suspend) a token if needed.

  • The ability to adopt EMVCo's network token standards with minimal integration efforts.

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

Limitations

Currently network tokens are only supported with tokens generated by Visa. The ability to use a network token must also be supported by the provider handling the transactions. Refer to the relevant provider guide to see whether a specific provider supports network tokens.

Registering for the Network Token Service

To use network tokens, you must first register for our Network Token Service. To do so, submit a request to our support department. We will then enable the service for you.

Using Network Tokens

Once you've registered for our Network Token Service, there's not much else you need to do to start using network tokens. Simply tokenize a user's card information using your preferred method of choice (REST API, Javascript API or Secure Fields Form). We will then generate a PaymentsOS token, and provision (request) a network token as well.

We need the customer's email address to provision a network token

Beware that we need the customer's email address in order to provision a network token. So make sure to provide it when collecting and tokenizing the user's card information.

Note that the network token is not returned directly to you, but kept by us. You simply pass the PaymentsOS token in the Create Authorization or Create Charge request (nothing new here); under-the-hood we'll then 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 request. Here's an example:

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

Network Tokens and Stored Card Credentials

Remember, a user's card information is always represented as a token and is thus stored as such (see Reusing Card Information). So when you generated the token and saved it in a customer object, we made sure to provision (request) a corresponding network token as well. You simply continue to use the saved token in the Create Authorization or Create Charge request (again, nothing new here) and we'll make sure that the network token is used instead. If you would like to get some more information about the network token that was provisioned for the token that you saved in a customer object, then you can call either the Retrieve a Payment Method request or the Retrieve all Payment Methods request. Information about the network token is then 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"
    }
  }
}
...

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 is then 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"
        }
      ]
}
...

You may be wondering, however, what will happen if you have stored your user's card credentials before signing up for the Network Token Service. No sweat! When you use the token to accept a payment, we will provision (request) a network token for that user and make sure that it is used when you authorize the transaction.

Did not include the customer's email address when creating the token or saving the customer information?

Remember that we need the customer's email address in order to provision a network token. If you did not include the email address when saving the token in the customer object or when creating the customer object, then you'll need to update the customer's information and add the email address.

Viewing the Status of the Network Token

If you'd like to see the status of the network token that we provisioned, including additional information about the network token, then you can check the response of the tokenization request that you invoked when you tokenized 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"
    }
  }
}
...

Managing a Network Token's Status

One of the advantages of using a network token, is that you can easily manage its status. For example, you can suspend a token and then reactivate it at a later stage if requested to do so by your customer.

To manage the status of a network token, use one of the following API requests:

Status Changes Requested by the 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.

results matching ""

    No results matching ""