Network Tokenization

Value Added Service
Canada
Europe & UK
United States

Overview

The Network Tokenization Service enables Paysafe to request payment tokens from Visa Token Service (VTS) and Mastercard Secure Card on File (SCoF) on behalf of the Merchant. These tokens replace the primary account number (PAN) of a debit or credit card, ensuring secure transaction processing. Each network token is issued by card schemes, visually resembling a regular card PAN with the same digit count. However, these tokens add an extra layer of security. When an issuing bank changes the details and status of a card, the details and status of the corresponding token are updated in real time.

As a registered Network Token Requestor for the service, you will gain the capability to conduct customer-initiated and merchant-initiated payments, refunds, original credits, and standalone credits within Europe using network tokens. This action replaces the use of card PANs that are underlying beneath Paysafe's permanent token.

You can access the service through Customer Vault API, Card API, and Payments API. Additionally, it's available through our hosted solutions: Paysafe.JS, Paysafe Checkout v1 and Paysafe Checkout v2.

Network tokens have three states: ACTIVE, SUSPENDED, and DELETED. The "status" field in the "networkToken" object indicates whether the token is ACTIVE or SUSPENDED. A DELETED token will not be returned by Customer Vault API/ Payments API on lookup.

Transactions can only be processed using active tokens. Transactions with suspended cards with network tokens will fail in our system with error 5500 but won't reach the issuing banks and affect the card acceptance rate. Suspended cards with network tokens are grayed out in Paysafe Checkout v1 and Paysafe Checkout v2. If you are integrated with Paysafe.JS or directly with our APIs, we recommend you graying out the suspended cards with network tokens on your checkout page on your behalf. At some point the suspended network tokens can be resumed to active by the customers or the issuing banks and this can be reflected on the frontend. Network tokens can be deleted by the card schemes or by the merchants/Paysafe. When a network token is deleted, the permanent token/ multi-use payment handle is deactivated on Paysafe's side, meaning that it will no longer be returned by Customer Vault API/ Payments API. If a transaction using the string of the deleted token/ payment handle (e.g. "SCdsav34r4b43bf") is attempted, an error code 5500 is returned.

If you wish to opt out of the service, you have the flexibility to do so at any time

Advantages

Extra layer of security for transactions with debit and credit cards
Reduced costs due to fewer failed transactions
Increase of the card acceptance rate
Improvement of the UX of customers with saved cards
Minor additional integration for merchants who are processing cards with Paysafe

Improved customer experience

Network tokenization provides issuing bank-defined card images to enhance the customer experience. Here are some examples of how this improved experience applies to Paysafe Checkout.

On a desktop:

On a mobile:

Card Brands

Visa
Mastercard

Product Availability

Onboarding and pricing solutions for direct merchants and platform partners (ISV and PayFac):
- Manual Onboarding
- ROB
- Applications API
- Accounts API v1
- Fee Redirect
- Gross Funding/Net Funding
Regions: EEA/UK and North America

Currently not supported:

Network tokenization with Mastercard for platform partners in EEA/UK and NA.

Setup Requirements

To create a test account in both the sandbox and production environments, Paysafe requires your consent to the Terms & Conditions Agreement for onboarding for the service.

Your website's or mobile app's checkout page must have the capability to support saved cards by the user.

For Network Tokenization upon saving a card or creating a profile, the Customer Vault and Payments API addresses the following requirements:

email (optional)
accountId (optional)
holderName or firstName and lastName (required)

Important considerations

When a new card is added to a new or existing profile using the Customer Vault API (or using the tokenization functionality of the Payments API), you can provide the Paysafe account id if you would like to fine-tune the account at which Network tokenization billing happens for that card/token. Otherwise, the Paysafe account id used for processing the card/token is also used for Network tokenization billing.
Including the email in the profile/customer is recommended, but not mandatory. Inclusion of the email may increase the chances of getting a Network token for a card.
If holderName is unavailable for the stored card, Paysafe automatically concatenates firstName and lastName from the customer's profile and sends the cardholder's name for network token creation.
initialTransactionId is a mandatory field for processing merchant-initiated recurring authorizations with Visa network tokens. If this reference is missing, the recurring authorizations are declined.

Transaction Types

Authorization
Void Authorization
Authorization + Settlement
Settlement
Recurring Authorization
Verification
Refund
Standalone Credit
Original Credit

Network Tokenization Diagram

Network Tokenization creation

Processing with network token

Typical Scenarios

Network token creation in Customer Vault

APIs to use

Customer Vault

Upon successfully authorizing a payment with CARD as the payment type, you must save the used debit or credit card on file within an existing customer profile or generate a new profile in the Customer Vault. In this process, add the merchant's accountId within the card object and place the customer's email address outside the card object, as shown in the example below. By following this procedure, the Network Tokenization Service will be activated, prompting the respective card network to generate a network token for the provided card.

Example

{

    "merchantCustomerId": "mycustomer1",

    "dupCheck": false,

    "locale": "en_GB",

    "firstName": "John",

    "lastName": "Doe",

    "email": "accountholder1@example.com",

    "card": {

        "accountId": "1006385560",

        "singleUseToken": "SCjaFaHN6Ud1y3ee"

    }

}

Paysafe will gradually backfill previously saved cards on file. For the purpose, please update the customer's profile with the customer's email address in case the email address hasn't been previously saved in Customer Vault. Paysafe automatically sends a default email address for network token creation, when the merchant is not keeping the customer's email on file. This way the merchant won't be required to pass neither an accountId nor an email to obtain a network token.

APIs to use

Customer Vault

Authorization with a network token in Cards API

APIs to use

Cards API

The generated permanent Paysafe token contains a unique network token, which is underlying beneath it along with the PAN. The permanent Paysafe token must be sent in the request body for authorization, but the transaction will be processed with the underlying network token and a single-use cryptogram, issued by the respective card scheme.

Network token creation in Payments API

APIs to use

Payments API

The network token is being created upon customer creation. The difference with the approach in Customer Vault is that accountId is not passed inside the card object in the request body for saving a card on file and the card object is not present at all. As the card is saved on file, a Paysafe multi-use payment handle is created.

Example

{

  "merchantCustomerId": "mycustomer2",

  "locale": "en_US",

  "paymentHandleTokenFrom": "SC1IHQO94g1ieppo",

  "accountId": "1006385561",

  "email": "accountholder2@example.com"

}

Paysafe will gradually backfill previously saved cards on file. For this purpose, please update the customer's profile with the customer's email address in case the email address wasn't previously saved in Payments API. Paysafe automatically sends a default email address for network token creation, when the merchant is not keeping the customer's email on file. This way the merchant won't be required to pass either an accountId or an email to obtain a network token.

APIs to use

Payments API

Authorization with a network token in Payments API

APIs to use

Payments API

For merchant-initiated transactions in Payments API you can directly pass the card's multi-use payment handle. A network token lies beneath this multi-use payment handle and the transaction will be processed with it instead of the real PAN.

Single-Use Payment Handle for network token

To create a single-use payment handle for a customer-initiated transaction with a saved card, first you have to create a Single-Use Customer Token.

APIs to use

Payments API

Afterwards the Single-Use Payment Handle can be created for a customer-initiated transaction with a saved card in Payments API, Paysafe.JS and Paysafe Checkout v2.

APIs to use

Payments API

The newly created Single-Use Payment Handle must be used for the authorization of the customer-initiated transaction. For more information about customer-initiated transactions with a single-use token/single-use payment handle, please visit the documentation for saved cards in Paysafe.JS and Paysafe Checkout.

Test Cards

You can use any of the following test card numbers to test network tokenization, simulate network token statuses and simulate 3DS scenarios. These test cards also work with Paysafe JS and Paysafe Checkout.

When using the test card numbers, you can use any date in the future for the expiry date (e.g. 11/27).

You can use any 3 digit number for the CVV in the merchant test environment.

Do not use real card numbers or other payment instrument details in the Merchant Test environment. It is not compliant with Payment Card Industry Data Security Standards (PCI-DSS), and does not protect cardholder/payee information. Any upload of real cardholder data is strictly prohibited.

Visa Credit Test Cards

Canada (CA)

Test card	threeDResult before challenge	Status before Challenge	threeDResult after challenge	Status after challenge	Network token status
4530917405317484	A	COMPLETED	N/A	N/A	Active
4530917441016967	C	PENDING	Y	COMPLETED	Active
4530918580995284	C	PENDING	N	COMPLETED	Active
4530913552729019	C	PENDING	U	COMPLETED	Active
4530917515475438	Error	N/A	N/A	N/A	Active
4530913908406585	N/A	FAILED	N/A	N/A	Active
4530918350065912	N	COMPLETED	N/A	N/A	Active
4530919415002742	R	COMPLETED	N/A	N/A	Active
4530912112018491	U	COMPLETED	N/A	N/A	Active
4530918758921674	Y	COMPLETED	N/A	N/A	Active
4530911131379272	N/A				Suspended

United States (US)

Test card	threeDResult before challenge	Status before Challenge	threeDResult after challenge	Status after challenge	Network token status
4037115932813277	A	COMPLETED	N/A	N/A	Active
4037111032905063	C	PENDING	Y	COMPLETED	Active
4037116914443950	C	PENDING	N	COMPLETED	Active
4037116732821023	C	PENDING	U	COMPLETED	Active
4037111029803297	Error	N/A	N/A	N/A	Active
4037118750096900	N/A	FAILED	N/A	N/A	Active
4037117422859406	N	COMPLETED	N/A	N/A	Active
4037118658703912	R	COMPLETED	N/A	N/A	Active
4037115678560231	U	COMPLETED	N/A	N/A	Active
4037110735384154	Y	COMPLETED	N/A	N/A	Active
4037112392039881	N/A				Suspended

United Kingdom (UK)

Test card	threeDResult before challenge	Status before Challenge	threeDResult after challenge	Status after challenge	Network token status
4107858933329042	A	COMPLETED	N/A	N/A	Active
4107853622419923	C	PENDING	Y	COMPLETED	Active
4107855469301643	C	PENDING	N	COMPLETED	Active
4107857399551834	C	PENDING	U	COMPLETED	Active
4107857962314453	Error	N/A	N/A	N/A	Active
4107851525956900	N/A	FAILED	N/A	N/A	Active
4107859143413030	N	COMPLETED	N/A	N/A	Active
4107856534681365	R	COMPLETED	N/A	N/A	Active
4107850911205559	U	COMPLETED	N/A	N/A	Active
4107852305054346	Y	COMPLETED	N/A	N/A	Active
4107854715295477	N/A				Suspended

Visa Debit Test Cards

Canada (CA)

Test card	threeDResult before challenge	Status before Challenge	threeDResult after challenge	Status after challenge	Network token status
4724093236113728	A	COMPLETED	N/A	N/A	Active
4724090529692871	C	PENDING	N	COMPLETED	Active
4724096257469143	C	PENDING	Y	COMPLETED	Active
4724099783775595	C	PENDING	U	COMPLETED	Active
4724094531751576	Error	N/A	N/A	N/A	Active
4724092115553731	N/A	FAILED	N/A	N/A	Active
4724096339651684	N	COMPLETED	N/A	N/A	Active
4724096742658730	R	COMPLETED	N/A	N/A	Active
4724095991134450	U	COMPLETED	N/A	N/A	Active
4724091366063184	Y	COMPLETED	N/A	N/A	Active
4724094535097737	N/A				Suspended

United States (US)

Test card	threeDResult before challenge	Status before Challenge	threeDResult after challenge	Status after challenge	Network token status
4900772901708419	A	COMPLETED	N/A	N/A	Active
4900777802203972	C	PENDING	N	COMPLETED	Active
4900775676721962	C	PENDING	Y	COMPLETED	Active
4900775962372421	C	PENDING	U	COMPLETED	Active
4900773140317558	Error	N/A	N/A	N/A	Active
4900772395170092	N/A	FAILED	N/A	N/A	Active
4900777203661752	N	COMPLETED	N/A	N/A	Active
4900771331142249	R	COMPLETED	N/A	N/A	Active
4900770048194485	U	COMPLETED	N/A	N/A	Active
4900770447068314	Y	COMPLETED	N/A	N/A	Active
4900774929900663	N/A				Suspended

United Kingdom (UK)

Test card	threeDResult before challenge	Status before Challenge	threeDResult after challenge	Status after challenge	Network token status
4206728076576578	A	COMPLETED	N/A	N/A	Active
4206725573218381	C	PENDING	Y	COMPLETED	Active
4206724525871579	C	PENDING	N	COMPLETED	Active
4206721678116018	C	PENDING	U	COMPLETED	Active
4206722159905317	Error	N/A	N/A	N/A	Active
4206721295360817	N/A	FAILED	N/A	N/A	Active
4206721826599867	N	COMPLETED	N/A	N/A	Active
4206728041727710	R	COMPLETED	N/A	N/A	Active
4206729470751858	U	COMPLETED	N/A	N/A	Active
4206722899684321	Y	COMPLETED	N/A	N/A	Active
4206724462896431	N/A				Suspended

Mastercard Credit Test Cards

Canada (CA)

Test card	threeDResult before challenge	Status before Challenge	threeDResult after challenge	Status after challenge	Network token status
5191338768452262	A	COMPLETED	N/A	N/A	Active
5191338497433336	C	PENDING	N	COMPLETED	Active
5191330088758395	C	PENDING	Y	COMPLETED	Active
5191332143743875	C	PENDING	U	COMPLETED	Active
5191339195870431	Error	N/A	N/A	N/A	Active
5191332663825581	N/A	FAILED	N/A	N/A	Active
5191332886136626	N	COMPLETED	N/A	N/A	Active
5191330922815179	R	COMPLETED	N/A	N/A	Active
5191330460502270	U	COMPLETED	N/A	N/A	Active
5191339185240447	Y	COMPLETED	N/A	N/A	Active
5191330476465413	N/A				Suspended

United States (US)

Test card	threeDResult before challenge	Status before Challenge	threeDResult after challenge	Status after challenge	Network token status
5100409118863928	A	COMPLETED	N/A	N/A	Active
5100403664506189	C	PENDING	Y	COMPLETED	Active
5100402864958174	C	PENDING	N	COMPLETED	Active
5100400390394393	C	PENDING	U	COMPLETED	Active
5100406923045980	Error	N/A	N/A	N/A	Active
5100406009532547	N/A	FAILED	N/A	N/A	Active
5100409189135446	N	COMPLETED	N/A	N/A	Active
5100408434950641	R	COMPLETED	N/A	N/A	Active
5100405364766310	U	COMPLETED	N/A	N/A	Active
5100402082737475	Y	COMPLETED	N/A	N/A	Active
5100403945379901	N/A				Suspended

United Kingdom (UK)

Test card	threeDResult before challenge	Status before Challenge	threeDResult after challenge	Status after challenge	Network token status
5186757524703295	A	COMPLETED	N/A	N/A	Active
5186759537382406	C	PENDING	Y	COMPLETED	Active
5186757558847604	C	PENDING	N	COMPLETED	Active
5186752024486491	C	PENDING	U	COMPLETED	Active
5186751594806179	Error	N/A	N/A	N/A	Active
5186756269467884	N/A	FAILED	N/A	N/A	Active
5186751859612825	N	COMPLETED	N/A	N/A	Active
5186757107966756	R	COMPLETED	N/A	N/A	Active
5186754745620002	U	COMPLETED	N/A	N/A	Active
5186756693781330	Y	COMPLETED	N/A	N/A	Active
5186751032314042	N/A				Suspended

Mastercard Debit Test Cards

Canada (CA)

Test card	threeDResult before challenge	Status before Challenge	threeDResult after challenge	Status after challenge	Network token status
6277411195338217	A	COMPLETED	N/A	N/A	Active
6277418703934205	C	PENDING	N	COMPLETED	Active
6277415526588051	C	PENDING	Y	COMPLETED	Active
6277418178693385	C	PENDING	U	COMPLETED	Active
6277418956680299	Error	N/A	N/A	N/A	Active
6277412354863995	N/A	FAILED	N/A	N/A	Active
6277417384125521	N	COMPLETED	N/A	N/A	Active
6277415971372308	R	COMPLETED	N/A	N/A	Active
6277418764212160	U	COMPLETED	N/A	N/A	Active
6277413259541579	Y	COMPLETED	N/A	N/A	Active
6277415211265544	N/A				Suspended

United States (US)

Test card	threeDResult before challenge	Status before Challenge	threeDResult after challenge	Status after challenge	Network token status
5036159366490465	A	COMPLETED	N/A	N/A	Active
5036157132498044	C	PENDING	N	COMPLETED	Active
5036155978980729	C	PENDING	Y	COMPLETED	Active
5036150778580522	C	PENDING	U	COMPLETED	Active
5036152993046552	Error	N/A	N/A	N/A	Active
5036151917586255	N/A	FAILED	N/A	N/A	Active
5036152760430898	N	COMPLETED	N/A	N/A	Active
5036155867412271	R	COMPLETED	N/A	N/A	Active
5036155077649522	U	COMPLETED	N/A	N/A	Active
5036155782320443	Y	COMPLETED	N/A	N/A	Active
5036152839230402	N/A				Suspended

United Kingdom (UK)

Test card	threeDResult before challenge	Status before Challenge	threeDResult after challenge	Status after challenge	Network token status
5573564584963681	A	COMPLETED	N/A	N/A	Active
5573560750426024	C	PENDING	N	COMPLETED	Active
5573568168853903	C	PENDING	Y	COMPLETED	Active
5573568746936105	C	PENDING	U	COMPLETED	Active
5573562527761931	Error	N/A	N/A	N/A	Active
5573563931740925	N/A	FAILED	N/A	N/A	Active
5573567306237284	N	COMPLETED	N/A	N/A	Active
5573562116464897	R	COMPLETED	N/A	N/A	Active
5573560487473380	U	COMPLETED	N/A	N/A	Active
5573562054389619	Y	COMPLETED	N/A	N/A	Active
5573567528287273	N/A				Suspended

Was this page helpful?

On this Page

Overview
Advantages
Card Brands
Product Availability
Setup Requirements
Transaction Types
Network Tokenization Diagram
Typical Scenarios
Test Cards
Visa Credit Test Cards
Visa Debit Test Cards
Mastercard Credit Test Cards
Mastercard Debit Test Cards

Search Overlay

Network Tokenization

Important considerations

Canada (CA)

United States (US)

United Kingdom (UK)

Canada (CA)

United States (US)

United Kingdom (UK)

Canada (CA)

United States (US)

United Kingdom (UK)

Canada (CA)

United States (US)

United Kingdom (UK)

Was this page helpful?

Thank you for your response!