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.

Using the PaymentsOS Network Token Service

When using the PaymentsOS Network Token Service, 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 PaymentsOS Network Token Service

To use network tokens provisioned by PaymentsOS, 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 Provisioned by PaymentsOS

Network tokens provisioned by PaymentsOS can only be used in transactions processed with stored their card credentials. So all you need to do is follow the steps in reusing card information for storing a customer's card details. As part of those steps, you will generate and store a PaymentsOS token that represents the user's card information. The moment you save that token, we will provision (request) a network token as well.

Note that the network token is not returned directly to you, but kept by us. You simply use the saved 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
  }
}
...

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.

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 provisioned by PaymentsOS, 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.

Webhook Events

If desired, you can receive a webhook notification when a network token is created or changes status. To do so, head over to your Webhooks configuration and enable the Create or Update event for Network Token alerts.

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

{
  "token_id": "10c14009-53ee-4ff9-9e1c-f44c423b3a9f",
  "created": "2021-11-01T11:51:57.156Z",
  "account_id": "164381dd-ef98-420c-83b6-78bbbdd1ea40",
  "network_token": {
    "provider_name": "VISA",
    "status": "ACTIVE",
    "created_timestamp": 1588848922,
    "modified_timestamp": 1588848922,
    "reference_id": "c137",
    "payment_account_reference": "par123",
    "card_media": {
      "logo_id": "uuid",
      "digital_card_art_id": "some_digital_card_art_id",
      "digital_card_art_background": "some_digital_card_art_background_id",
      "digital_card_art_foreground": "some_digital_card_art_foreground",
      "digital_card_art_background_combined_id": "some_digital_card_art_background_combined_id"
    }
  }
}

Using a Network Token Requested by a Third-Party Token Provider

If desired, you can also use a network token that 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 request. In the payment_method.card_number field, pass the network token. Here's an example:

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

Using Network Tokens Requested by ApplePay

Provider Support

The functionality outlined below is currently only supported through integrations with Shva.

If you obtained a network token through ApplePay, then you can decrypt the payload to extract the network token and pass the token to PaymentsOS in the Create Authorization or Create Charge request. Just make sure to specify ApplePay as the token provider in the payment_method.token_provider field, and pass the token itself in the payment_method.card_number field:

...
{
"payment_method": {
    "source_type": "network_token",
    "type": "untokenized",
    "token_provider": "ApplePay",
    "expiration_date": "22-2030",
    "card_number": "4242424242424242"
  }
}
...

Passing the ApplePay payload 'as is' to the provider

Depending on the provider you integrated with, you can also pass the ApplePay payload 'as is' (that is, without decrypting it) and have the provider extract the network token for you. This functionality is currently supported with PayU Single Platform and PayU Russia.

results matching ""

    No results matching ""