External Network Tokens
External network tokens are network tokens that are issued by another payment service provider. They serve as a 16-digit alternative to the primary account number (PAN) of a debit or credit card.
A network token cryptogram is a short, encrypted code that can only be used once, generated by the card scheme. It is required for customer-initiated transactions and for transactions that involve an updated network token, regardless of whether the transaction is initiated by a customer or a merchant.
This functionality is particularly beneficial if you have a high number of PCI requirements (i.e. you are responsible for handling card data) and have already integrated network tokenization with another payment service provider, or implemented Visa and/ or Mastercard Click to Pay.
When working with external network tokens, here are some important points to note:
-
Token lifecycle management
As external network tokens are issued by a third-party provider, we do not manage their lifecycle. Consequently, we do not support the saving of external network tokens. -
Token cryptogram
You are required to provide a network token cryptogram for customer-initiated transactions. -
Token updates
If an external network token is updated, you must include the network token cryptogram in your next transaction request. -
Transaction fees
Please be aware that scheme fees from Mastercard and Visa for processing external network tokens apply.
Processing external network tokens
You can process external network token transactions using the Paysafe Payments API or the Cards API.
Using the Payments API
- Create a single-use payment handle using the external network token details.
POST /paymenthub/v1/paymenthandles
{
"merchantRefNum": "{{$guid}}",
"transactionType": "PAYMENT",
"amount": 100,
"settleWithAuth": true,
"accountId":"1002231860",
"card": {
"holderName":"John Doe",
"tokenType": "NETWORK_TOKEN",
"networkToken": {
"token": "5200000000002151",
"cryptogram": "MFNyroCRmAPANZWxrEK4TgACVUA=",
"expiry": {
"month": 10,
"year": 2025
}
}
},
"billingDetails": {
"nickName": "Home",
"street": "abcd",
"city": "defg",
"state": "AL",
"country": "US",
"zip": "94404"
},
"profile": {
"firstName": "Joe",
"lastName": "Smith",
"email": "Joe.Smith@canada.com"
},
"paymentType": "CARD",
"currencyCode": "USD",
"customerIp": "172.0.0.1",
"skip3ds": "false",
"threeDs": {
"merchantUrl": "https://api.qa.paysafe.com/checkout/v2/index.html#/desktop",
"deviceChannel": "BROWSER",
"messageCategory": "PAYMENT",
"transactionIntent": "CHECK_ACCEPTANCE",
"authenticationPurpose": "PAYMENT_TRANSACTION",
"requestorChallengePreference": "NO_PREFERENCE"
},
"returnLinks": [
{
"rel": "on_completed",
"href": "https://www.paysafe.com/en/",
"method": "GET"
},
{
"rel": "on_failed",
"href": "https://www.paysafecard.com/bg/",
"method": "GET"
},
{
"rel": "default",
"href": "https://www.google.com",
"method": "GET"
}
]
}
{
"id": "e4bf480f-848f-4b61-94a4-98b080c85245",
"accountId": "1002231860",
"paymentType": "CARD",
"paymentHandleToken": "NzleNRfxov5Ss6F",
"merchantRefNum": "2866c7ee-1903-46e7-ba0d-d3fe38049539",
"currencyCode": "USD",
"txnTime": "2024-12-12T12:26:26Z",
"billingDetails": {
"nickName": "Home",
"street": "abcd",
"city": "defg",
"zip": "94404",
"state": "AL",
"country": "US"
},
"customerIp": "172.0.0.1",
"status": "PAYABLE",
"amount": 100,
"action": "NONE",
"usage": "SINGLE_USE",
"timeToLiveSeconds": 899,
"transactionType": "PAYMENT",
"executionMode": "SYNCHRONOUS",
"profile": {
"locale": "en",
"firstName": "Joe",
"lastName": "Smith",
"email": "Joe.Smith@canada.com"
},
"card": {
"cardExpiry": {
"month": "10",
"year": "2025"
},
"cardType": "MC",
"cardBin": "520000",
"lastDigits": "2151",
"cardCategory": "CREDIT",
"issuingCountry": "US",
"networkToken": {
"bin": "520000",
"lastDigits": "2151",
"expiry": {
"month": "10",
"year": "2025"
}
},
"tokenType": "NETWORK_TOKEN"
},
"returnLinks": [
{
"method": "GET",
"rel": "on_completed",
"href": "https://www.paysafe.com/en/"
},
{
"method": "GET",
"rel": "on_failed",
"href": "https://www.paysafecard.com/bg/"
},
{
"method": "GET",
"rel": "default",
"href": "https://www.google.com"
}
],
"skip3ds": false,
"threeDs": {
"merchantUrl": "https://api.qa.paysafe.com/checkout/v2/index.html#/desktop",
"deviceChannel": "BROWSER",
"requestorChallengePreference": "NO_PREFERENCE",
"messageCategory": "PAYMENT",
"transactionIntent": "CHECK_ACCEPTANCE",
"authenticationPurpose": "PAYMENT_TRANSACTION"
}
}
- Create a payment using the single-use payment handle token received in the payment handle response.
NOTE: External network tokens always begin with the letter N.
POST /paymenthub/v1/payments
{
"merchantRefNum": "{{$guid}}",
"amount": 100,
"currencyCode": "USD",
"dupCheck": true,
"settleWithAuth": false,
"paymentHandleToken": "NzleNRfxov5Ss6F",
"customerIp": "10.10.12.64",
"description": "Netflix GBR"
}
{
"id": "36943680-88ee-457d-8153-35742557e5bf",
"paymentType": "CARD",
"paymentHandleToken": "NzleNRfxov5Ss6F",
"merchantRefNum": "83efc6ea-d9c9-4ddb-8060-32f65f113f24",
"currencyCode": "USD",
"settleWithAuth": false,
"txnTime": "2024-12-12T12:26:38Z",
"billingDetails": {
"nickName": "Home",
"street": "abcd",
"city": "defg",
"zip": "94404",
"state": "AL",
"country": "US"
},
"customerIp": "10.10.12.64",
"status": "COMPLETED",
"amount": 100,
"preAuth": false,
"description": "Netflix GBR",
"availableToSettle": 100,
"gatewayResponse": {
"authCode": "631085",
"avsResponse": "MATCH",
"cvvVerification": "NOT_PROCESSED",
"serializable": true
},
"merchantDescriptor": {
"dynamicDescriptor": "DD Line 1",
"phone": "000-111000099"
},
"profile": {
"locale": "en",
"firstName": "Joe",
"lastName": "Smith",
"email": "Joe.Smith@canada.com"
},
"card": {
"cardExpiry": {
"month": "10",
"year": "2025"
},
"cardType": "MC",
"cardBin": "520000",
"lastDigits": "2151",
"cardCategory": "CREDIT",
"issuingCountry": "US",
"networkToken": {
"lastDigits": "2151",
"expiry": {
"month": "10",
"year": "2025"
}
},
"tokenType": "NETWORK_TOKEN"
}
}
Using the Cards API
- Create a payment, passing the external network token details within the card object.
POST /cardpayments/v1/accounts/(account_id)/auths
{
"merchantRefNum": "{{$guid}}",
"amount": "7",
"settleWithAuth": false,
"card": {
"tokenType": "NETWORK_TOKEN",
"networkToken": {
"token": "5200000000002151",
"cryptogram": "MFNyroCRmAPANZWxrEK4TgACVUA=",
"expiry": {
"month": 10,
"year": 2025
}
}
},
"billingDetails": {
"city": "Smiths Falls",
"country": "CA",
"state": "ON",
"street": "Aberdeen Ave",
"street2": "No. 96",
"zip": "M5H"
}
}
{
"id": "142bd53a-eefc-4fdc-b823-e45a2aa675bd",
"merchantRefNum": "7bf6a182-8978-45fa-b568-ae65f5ae6b3f",
"txnTime": "2024-12-12T12:21:18Z",
"status": "COMPLETED",
"amount": 7,
"settleWithAuth": false,
"preAuth": false,
"availableToSettle": 7,
"card": {
"tokenType": "NETWORK_TOKEN",
"networkToken": {
"expiry": {
"month": 10,
"year": 2025
},
"lastDigits": "2151"
},
"type": "MC",
"lastDigits": "2151",
"cardExpiry": {
"month": 10,
"year": 2025
},
"issuingCountry": "US"
},
"authCode": "130358",
"billingDetails": {
"street": "Aberdeen Ave",
"street2": "No. 96",
"city": "Smiths Falls",
"state": "ON",
"country": "CA",
"zip": "M5H"
},
"merchantDescriptor": {
"dynamicDescriptor": "DD Line 1",
"phone": "000-111000099"
},
"visaAdditionalAuthData": {},
"currencyCode": "USD",
"avsResponse": "MATCH",
"cvvVerification": "NOT_PROCESSED",
"links": [
{
"rel": "self",
"href": "https://api.test.paysafe.com/cardpayments/v1/accounts/1002231860/auths/142bd53a-eefc-4fdc-b823-e45a2aa675bd"
}
]
}
Testing instructions
As the external network token format matches that of a regular PAN, you can use our Visa and Mastercard test card numbers during testing.
- For testing non-3DS flow, use the test card numbers on the Payments API Test Cards page.
- For testing 3DS flow, use the test card numbers on the 3DS Test Cards page.
You can use the following test cryptograms:
- Mastercard cryptogram: MFNyroCRmAPANZWxrEK4TgACVUA=
- Visa cryptogram: YwAAABDDEDqZemoRR24MgA2bHAA