Use third-party network tokens

DocsCurrent

Last updated: Oct 29th, 9:24am

PayPal supports third-party network token processing for merchants and partners.

Availability

This integration is available:

In the US.
In beta in the following countries:
- Australia
- Canada
- European Union
- United Kingdom

For more information, contact Sales.

Tokenization

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:

Improved authorization rates.
Increased security by reducing opportunities for data theft and using cryptograms to protect credentials.
Potentially reduced transaction-processing costs.
Simplified payment processing.
Helps maintain Payment Card Industry Data Security Standard compliance.

Third-party network token

A third-party network token represents a payment method that is either:

Saved in-house by the partner or merchant.
Saved by an external Token Service Provider (TSP).

Third-party network token processing happens when PayPal processes a payment using a token that PayPal didn't create.

How it works

Integrate with third-party network token payments as follows:

Save and tokenize a payer's payment method.
Get a token number and expiration date to use for payments.
Use this token when sending a payment through PayPal.
PayPal processes the payment as a regular credit or debit card purchase.

Note: Third-party tokens aren't stored and can't be created, mapped, unmapped, or validated against their primary account number.

Know before you code

You'll need an Advanced Credit and Debit Card payments integration.
You acknowledge and agree that you are solely responsible for any third-party vaulting (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.

Using third-party network tokens with PayPal

Review this section to learn how to integrate third-party network tokens in your multiparty 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 multiparty request creates a new order and completes the payment in a single step by declaring the intent as CAPTURE:

Sample request

The payment request includes the new network_token and stored_credential objects:

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
2-H 'Content-Type: application/json' \
3-H 'PayPal-Request-Id: REQUEST-ID' \
4-H 'Authorization: Bearer ACCESS-TOKEN' \
5-d '{
6  "intent": "CAPTURE",
7  "purchase_units": [
8      {
9        "reference_id": "REFID-000-1001",
10        "description": "Item bought at This Store",
11        "custom_id": "1111",
12        "soft_descriptor": "",
13        "amount": {
14            "currency_code": "USD",
15            "value": "100.00"
16        },
17        "shipping": {
18            "address": {
19                "address_line_1": "123 Main St.",
20                "address_line_2": "",
21                "admin_area_2": "Anytown",
22                "admin_area_1": "CA",
23                "postal_code": "12345",
24                "country_code": "US",
25              },
26          },
27        "payee": {
28            "email_address": "payer@example.com"
29          }
30      }
31  ],
32  "payment_source": {
33      "card": {
34          "name": "Firstname Lastname",
35          "network_token": {
36              "number": "4420567383232198",
37              "expiry": "2030-11",
38              "eci_flag": "NON_3D_SECURE_TRANSACTION",
39              "token_requestor_id": "12324",
40            },
41          "stored_credential": {
42              "payment_initiator": "MERCHANT",
43              "payment_type": "UNSCHEDULED",
44              "usage": "SUBSEQUENT",
45              "previous_network_transaction_reference": {
46                    "id": "123456789016848",
47                    "network": "VISA"
48              }
49          }
50      }
51  }
52}'

Lines 35-40: 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 38: 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 following table. 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.

Sample response

The HTTP 201 response includes the new bin_details and network_transaction_reference objects:

1{
2    "id": "1C882901H6992113A",
3    "status": "COMPLETED",
4    "payment_source": {
5        "card": {
6            "name": "Firstname Lastname",
7            "last_digits": "7287",
8            "expiry": "2030-11",
9            "brand": "VISA",
10            "available_networks": [
11                "VISA"
12            ],
13            "type": "CREDIT",
14            "bin_details": {
15                "bin": "43999450",
16                "issuing_bank": "CREDIT UNION OF OHIO",
17                "bin_country_code": "US"
18            }
19        }
20    },
21    "purchase_units": [
22        {
23            "reference_id": "REFID-000-1001",
24            "payment_instruction": {
25                ...
26            },
27            "shipping": {
28                ...
29            },
30            "payments": {
31                "captures": [
32                    {
33                        "id": "3BJ29575M0175253F",
34                        "status": "COMPLETED",
35                        "amount": {
36                            "currency_code": "USD",
37                            "value": "50.00"
38                        },
39                        "final_capture": true,
40                        "disbursement_mode": "DELAYED",
41                        "seller_protection": {
42                            "status": "NOT_ELIGIBLE"
43                        },
44                        "seller_receivable_breakdown": {
45                            ...
46                        },
47                        "invoice_id": "INVID-21-07-2023-05-56-55",
48                        "custom_id": "CUSTOMID-1001",
49                        "links": [
50                            ...
51                        ],
52                        "create_time": "2023-07-21T12:27:00Z",
53                        "update_time": "2023-07-21T12:27:00Z",
54                        "processor_response": {
55                            "avs_code": "Y",
56                            "cvv_code": "X",
57                            "response_code": "0000"
58                        },
59                        "network_transaction_reference": {
60                            "id": "054706134140378",
61                            "network": "VISA"
62                        }
63                    }
64                ]
65            }
66        }
67    ],
68    "links": [
69        ...
70    ]
71}

Lines 14-18: The payment_source.card.bin_details object contains the bank identification number (BIN) information. See bin_details for more details.
Lines 59-62: The purchase_units.payments.captures.network_transaction_reference object includes the id and network name. See network_transaction_reference for more details.