On this page
No Headings
Last updated: June 7, 2026
PayPal supports third-party network token processing for merchants and partners.
This integration is available in the following countries:
For more information, contact Sales.
Tokenization keeps payment information private by turning card numbers into unique tokens, which are stored securely and used instead of the original card.
Tokenization creates a unique credential, or token, for a card that is different from its 15- or 16-digit primary account number. The merchant only sends the token, rather than the underlying account number. A network token only works for a specific card and merchant.
The benefits of using network tokens include:
A third-party network token represents a payment method that is either:
Third-party network token processing happens when PayPal processes a payment using a token that PayPal didn't create.
Integrate with third-party network token payments as follows:
Note: Third-party tokens aren't stored and can't be created, mapped, unmapped, or validated against their primary account number.
You'll need a PayPal Expanded Checkout integration.
You acknowledge and agree that you are solely responsible for any third-party vaulting functionality (not provided by PayPal) that you use and PayPal will, under no circumstances, be responsible or liable for any damages, losses or costs whatsoever suffered or incurred by you as a result of using a third-party vaulting functionality on PayPal's platforms (including Products), services, or APIs.
Note: Third-party network token integrations don't support reference or future transactions. Don't pass a reference transaction ID using the payment_source.token.id parameter.
Review this section to learn how to integrate third-party network tokens in your PayPal integration.
This code sample shows a third-party network token in the body of a POST call to the Create order endpoint of the Orders v2 API. This request creates a new order and completes the payment in a single step by declaring the intent as CAPTURE.
The payment request includes the new network_token and stored_credential objects:
curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
-H 'Content-Type: application/json' \
-H 'PayPal-Request-Id: REQUEST-ID' \
-H 'Authorization: Bearer ACCESS-TOKEN' \
-d '{
"intent": "CAPTURE",
"purchase_units": [
{
"reference_id": "REFID-000-1001",
"amount": {
"currency_code": "USD",
"value": "100.00"
}
}
],
"payment_source": {
"card": {
"name": "Firstname Lastname",
"network_token": {
"number": "4444444444444444",
"expiry": "2030-11",
"eci_flag": "NON_3D_SECURE_TRANSACTION",
"token_requestor_id": "12324"
},
"stored_credential": {
"payment_initiator": "MERCHANT",
"payment_type": "UNSCHEDULED",
"usage": "SUBSEQUENT",
"previous_network_transaction_reference": {
"id": "NETWORK-TRANSACTION-REFERENCE-ID",
"network": "VISA"
}
}
}
}
}'Lines 19-24: The payment_source.card.network_token object contains details about the third-party network token. PayPal passes this information to the issuer. See network_token for more details.
Line 22: Token service providers give each third-party network token a 2-digit Electronic Commerce Indicator (ECI) code. When you make a payment using a third-party network token, your integration needs to change the 2-digit ECI code to the corresponding string from the table below. Pass this value using the payment_source.card.network_token.eci_flag parameter. This value is required for customer-initiated payments and optional for merchant-initiated payments:
| Numeric ECI code | String |
|---|---|
00 | MASTERCARD_NON_3D_SECURE_TRANSACTION |
07 | NON_3D_SECURE_TRANSACTION |
Lines 25-33: The payment_source.card.stored_credential object contains details about the type of card-on-file payment. See stored_credential for more details.
The HTTP 201 response includes the new bin_details and network_transaction_reference objects:
{
"id": "ORDER-ID",
"status": "COMPLETED",
"payment_source": {
"card": {
"name": "Firstname Lastname",
"last_digits": "4444",
"expiry": "2030-11",
"brand": "VISA",
"available_networks": [
"VISA"
],
"type": "CREDIT",
"bin_details": {
"issuing_bank": "CREDIT UNION OF OHIO",
"bin_country_code": "US",
"products": [
"CONSUMER"
]
}
}
},
"purchase_units": [
{
"reference_id": "REFID-000-1001",
"payment_instruction": {
...
},
"shipping": {
...
},
"payments": {
"captures": [
{
"id": "ORDER-ID",
"status": "COMPLETED",
"amount": {
"currency_code": "USD",
"value": "50.00"
},
"final_capture": true,
"disbursement_mode": "DELAYED",
"seller_protection": {
"status": "NOT_ELIGIBLE"
},
"seller_receivable_breakdown": {
...
},
"invoice_id": "INVID-21-07-2023-05-56-55",
"custom_id": "CUSTOMID-1001",
"links": [
...
],
"create_time": "2023-07-21T12:27:00Z",
"update_time": "2023-07-21T12:27:00Z",
"processor_response": {
"avs_code": "Y",
"cvv_code": "X",
"response_code": "0000"
},
"network_transaction_reference": {
"id": "NETWORK-TRANSACTION-REFERENCE-ID",
"network": "VISA"
}
}
]
}
}
],
"links": [
...
]
}payment_source.card.bin_details object contains the bank identification number (BIN) information. See bin_details for more details.purchase_units.payments.captures.network_transaction_reference object includes the id and network name. See network_transaction_reference for more details.In the PayPal sandbox, you can use test cards to simulate third-party network token payment scenarios.
The test scenario on this page shows a successful payment capture with the following details:
Use the following test cards as third-party network tokens. Pass the test card number in the body of the request using payment_source.card.network_token.number.
Tip: Enter a future expiration date when testing these card network tokens.
| Card brand | Test card | Cryptogram |
|---|---|---|
| Visa | 4034772286582057 | "cryptogram":"ApIPtIgAMyrMgTx1RSnAMAACAAA=" |
| Visa | 4556871409493313 | "cryptogram":"ApIPtIgAMyrMgTx1RSnAMAACAAA=" |
| Mastercard | 5530238208956601 | "cryptogram":"ApIPtIgAMyrMgTx1RSnAMAACAAA=" |
| Mastercard | 5419720028804901 | "cryptogram":"ApIPtIgAMyrMgTx1RSnAMAACAAA=" |
| Amex | 379015087078375 | "cryptogram":"ApIPtIgAMyrMgTx1RSnAMAACAAA=" |
| Discover | 6011390662682995 | "cryptogram":"ApIPtIgAMyrMgTx1RSnAMAACAAA=" |
Test the third-party network payment token for each card brand by sending a POST call to the Capture payment for order endpoint of the Orders v2 API with the following values:
payment_source.card.network_token.number parameter.payment_source.card.network_token.expiry.ApIPtIgAMyrMgTx1RSnAMAACAAA= using the payment_source.card.network_token.cryptogram parameter.payment_source.card.network_token.eci_flag parameter. For MasterCard, pass MASTERCARD_NON_3D_SECURE_TRANSACTION. For other cards, pass NON_3D_SECURE_TRANSACTION.The transaction starts when you send a POST call to the Create order endpoint of the Orders v2 API.
A successful create order request returns the HTTP 201 Created status code and a JSON response body that includes by default a minimal response with the ID, status, and HATEOAS links.
Capture URL: https://api-m.sandbox.paypal.com/v2/checkout/orders
curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS-TOKEN' \
-H 'PayPal-Partner-Attribution-Id: BN-CODE' \
-H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
-H 'PayPal-Request-Id: REQUEST-ID' \
-d '{
"intent": "CAPTURE",
"purchase_units": [
{
"reference_id": "reference_id_1_5.00",
"payment_group_id": "1",
"description": "Description of PU-1",
"custom_id": "custom_id_1_5.00",
"soft_descriptor": "soft_descr_1_5.00",
"invoice_id": "invoice_id_create_order_1_1740637790",
"amount": {
"currency_code": "USD",
"value": "5.00",
"breakdown": {
"item_total": {
"currency_code": "USD",
"value": "5.00"
},
"shipping": {
"currency_code": "USD",
"value": "0.00"
},
"handling": {
"currency_code": "USD",
"value": "0.00"
},
"tax_total": {
"currency_code": "USD",
"value": "0.00"
},
"gift_wrap": {
"currency_code": "USD",
"value": "0.00"
},
"shipping_discount": {
"currency_code": "USD",
"value": "0.00"
}
}
},
"items": [
{
"name": "Mug",
"description": "Coffee Mug",
"sku": "259483234812",
"unit_amount": {
"currency_code": "USD",
"value": "5.00"
},
"tax": {
"currency_code": "USD",
"value": "0.00"
},
"quantity": "1",
"category": "DIGITAL_GOODS"
},
{
"name": "Mark-Up (0%)",
"description": "Buyer Mark-Up Amount",
"sku": "2594832348111",
"unit_amount": {
"currency_code": "USD",
"value": "0.00"
},
"tax": {
"currency_code": "USD",
"value": "0.00"
},
"quantity": "1",
"category": "DIGITAL_GOODS"
}
],
"payee": {
"email_address": "[email protected]",
"display_data": {
"business_email": "[email protected]",
"brand_name": "PayPal Shop",
"business_phone": {
"country_code": "39",
"national_number": "222-222-2222",
"extension_number": "1"
}
}
},
"payment_instruction": {
"disbursement_mode": "INSTANT",
"platform_fees": [
{
"amount": {
"currency_code": "USD",
"value": "1.25"
},
"payee": {
"email_address": "[email protected]"
}
}
],
"payee_pricing_tier_id": ""
},
"shipping": {
"address": {
"shipping_name": "Firstname Lastname",
"phone": "555-555-5555",
"address_line_1": "123 Main St.",
"address_line_2": "#100",
"admin_area_1": "CA",
"admin_area_2": "Anytown",
"postal_code": "12345",
"country_code": "US",
"address_details": {}
},
"method": "UPS"
}
}
],
"payment_source": {
"card": {
"network_token": {
"number": "4444444444444444",
"expiry": "2029-01",
"cryptogram": "ApIPtIgAMyrMgTx1RSnAMAACAAA=",
"eci_flag": "NON_3D_SECURE_TRANSACTION",
"token_requestor_id": "VK123PTR"
}
}
},
"application_context": {
"locale": "en-US",
"landing_page": "BILLING",
"shipping_preference": "SET_PROVIDED_ADDRESS",
"user_action": "PAY_NOW",
"return_url": "https://example.com/returnUrl",
"cancel_url": "https://example.com/cancelUrl"
}
}'The following code sample shows a capture order request using a third-party network token for a Visa card. The response includes a network_transaction_reference object showing the network transaction reference ID, and the card network, Visa. The Visa network doesn't return an expiration date.
Capture URL: https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/capture
curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/{ORDER-ID}/capture \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS-TOKEN' \
-H 'PayPal-Partner-Attribution-Id: BN-CODE' \
-H 'PayPal-Auth-Assertion: AUTH-ASSERTION-JWT' \
-H 'PayPal-Request-Id: REQUEST-ID' \
-d '{
"payment_source": {
"card": {
"network_token": {
"number": "4444444444444444",
"expiry": "2029-01",
"cryptogram": "ApIPtIgAMyrMgTx1RSnAMAACAAA=",
"eci_flag": "NON_3D_SECURE_TRANSACTION",
"token_requestor_id": "VK123PTR"
}
}
}
}'A successful response to a non-idempotent request returns the HTTP 201 Created status code with a JSON response body that shows captured payment details, including a network_transaction_reference object. If the order request was already processed, the endpoint returns the HTTP 200 OK status code to indicate an idempotent response.
The network_transaction_reference object passes the reference values used by the card network to identify this transaction. See network_transaction_reference for details.