Integration - Paypal Docs

This guide walks through the end-to-end implementation of Ecommerce network tokenization using Secure Credential Services by PayPal.

Prerequisites

To integrate with Secure Credential Services, you need:

A PayPal account with a Client ID provisioned for Ecommerce tokenization
OAuth 2.0 credentials (Client ID and Client Secret)
Required API scopes provisioned by the PayPal team for your use case
A decision on your TRID model

Note: Contact your PayPal account representative to obtain sandbox OAuth credentials and confirm your TRID model before starting. Configure sandbox and production environments separately: never share credentials between environments.

API reference

Use the following base URLs and endpoints for all Payment Tokenization requests.

Base URLs

All paths are prefixed /v1/payment-tokenization/. All PayPal REST API requests target one of two base URLs:

Environment	URL
Sandbox	`https://api-m.sandbox.paypal.com`
Production	`https://api-m.paypal.com`

List of APIs

Method	Endpoint	Purpose	Requirement
`POST`	`/v1/payment-tokenization/enrollments`	Create a real-time token enrollment for a single card	Mandatory
`GET`	`/v1/payment-tokenization/enrollments/{id}`	Retrieve enrollment details and token information	Mandatory
`POST`	`/v1/payment-tokenization/payment-credentials`	Fetch or pre-fetch a one-time payment cryptogram for a transaction	Mandatory
`POST`	`/v1/payment-tokenization/enrollments/{id}/close`	Permanently close a token enrollment	Mandatory
`GET`	`/v1/payment-tokenization/contents/{content_id}`	Retrieve card art, terms & conditions, or logos for a tokenized card	Mandatory
`POST`	`/v1/payment-tokenization/batch-requests`	Submit a bulk enrollment batch (up to 1,000 cards)	Mandatory
`GET`	`/v1/payment-tokenization/batch-requests/{id}`	Retrieve the status and results of a bulk enrollment batch	Mandatory
`POST`	`/v1/payment-tokenization/token-requestors`	Create and onboard a new Token Requestor (TRID)	Recommended
`GET`	`/v1/payment-tokenization/token-requestors/{tokenRequestorId}`	Retrieve TRID configuration, status, and supported networks	Recommended
`POST`	`/v1/payment-tokenization/search-token-requestors`	Search for TRIDs by name, status, or supported network	Recommended
`POST`	`/v1/payment-tokenization/search-enrollments`	Search enrollments by merchant, partner, token reference, or status	Recommended
`POST`	`/v1/payment-tokenization/enrollments/{id}/activate`	Reactivate a previously suspended enrollment	Recommended
`POST`	`/v1/payment-tokenization/enrollments/{id}/suspend`	Temporarily suspend a token enrollment	Recommended

Authentication

All API calls require an OAuth 2.0 Bearer token obtained from the PayPal token endpoint.

# Obtain a token:
POST https://api-m.sandbox.paypal.com/v1/oauth2/token
Authorization: Basic <Base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=<required_scope>

# Pass the token in every request
Authorization: Bearer <access_token>

Bearer tokens expire after approximately 8-9 hours. Implement token caching and refresh logic in your client. Do not request a new token on every API call.

Note: The required API scopes for Ecommerce tokenization must be provisioned by the PayPal team before you begin. Work with your PayPal account representative to confirm the correct scopes for your integration.

Steps for integration

Complete the following steps in order to set up your environment, onboard your TRID, and enroll cards for Ecommerce tokenization. Depending on your use case, enrollment uses either real-time provisioning, where a cardholder adds or updates a card in an interactive flow, or bulk provisioning, which tokenizes existing cards-on-file at scale.

1. Set up PayPal sandbox environment

The sandbox is where you test end-to-end using simulators and mocked data — no real authorizations or settlements occur. What you need from PayPal’s integration team:

OAuth client credentials (Client ID and Secret)
One or more sandbox TRIDs aligned to your business model
Required authorization scopes

Environment configuration:

PayPal sandbox base URL: api-m.sandbox.paypal.com
Production base URL: api-m.paypal.com
API calls follow the pattern: https://{base-url}/v1/payment-tokenization/{resource}

Keep sandbox and live environment credentials completely separate — never share them between environments.

2. Onboard your Token Requestor ID (TRID)

To enable tokenization across supported card networks, merchants must first complete onboarding for tokenization. A TRID is a unique identifier issued to a token requestor that enables them to securely request network tokens from card networks.

POST /v1/payment-tokenization/token-requestors

Provide your merchant name, partner name, client credentials, and product template. The response returns your paypal_token_requestor_id along with per-network sub-product TRIDs for Visa VTS, Mastercard MDES, American Express AETS, and Discover DDX.

Sample request
Sample response (201 Created)

curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/token-requestors' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-d '{
    "merchant_name": "MerchantName",
    "merchant_account_id": "SZEKQNBKSSQ8L",
    "client_credentials": [
        { "client_id": "asc7678akneqmdalkuf0wj==" },
        { "tenant_name": "TenantName" }
    ],
    "partner_name": "PARTNER_NAME",
    "product_templates": ["PARTNER_TEMPLATE_NAME"],
    "external_reference_id": "extRefId"
}'

{
  "id": "<TRID_ID>",
  "status": "ACTIVE",
  "paypal_token_requestor_id": "<TRID_ID>",
  "merchant_name": "MerchantName",
  "partner_name": "PARTNER_NAME",
  "external_reference_id": "extRefId",
  "merchant_account_id": "SZEKQNBKSSQ8L",
  "additional_attributes": [],
  "products": [
    {
      "product_name": "COF_WALLET_PROVIDER",
      "instrument_product_name": "PPWALLET_COF_ACQUIRING_NTT",
      "status": "ACTIVE",
      "additional_attributes": [],
      "sub_products": [
        {
          "product_name": "COF_ACQUIRING_ECOM_DDX_TPAN",
          "product_type": "OPEN_LOOP_SINGLE_USE",
          "token_requestor_id": { "token_service_provider": "DDX", "value": "<DDX_TRID_ID>" },
          "status": "ACTIVE",
          "additional_attributes": []
        },
        {
          "product_name": "COF_ACQUIRING_ECOM_VTS_TPAN",
          "product_type": "OPEN_LOOP_SINGLE_USE",
          "token_requestor_id": { "token_service_provider": "VTS", "value": "<VTS_TRID_ID>" },
          "status": "ACTIVE",
          "additional_attributes": [
            { "name": "DEVICE_ENROLLMENT_PRODUCT", "value": "VTS_DEVICE_ENROLLMENT_TOKEN" },
            { "name": "DEVICE_BINDING_PRODUCT", "value": "VTS_DEVICE_BINDING_TOKEN" }
          ]
        },
        {
          "product_name": "COF_ACQUIRING_ECOM_AETS_TPAN",
          "product_type": "OPEN_LOOP_SINGLE_USE",
          "token_requestor_id": { "token_service_provider": "AETS", "value": "<AETS_TRID_ID>" },
          "status": "ACTIVE",
          "additional_attributes": []
        }
      ]
    }
  ]
}

Once registered, verify your TRID with these two calls before proceeding:

GET …/token-requestors/{tokenRequestorId}: confirm your config and supported networks
POST …/search-token-requestors: useful in multi-TRID setups to discover TRIDs by name or status

3. Determine minimum API implementation for your business model

Business Model	Must-Have APIs	Optional
Merchant	TRID Mgmt, Enroll, Payment Credential, Lifecycle Mgmt, Webhooks	Bulk Enrollment
Marketplace	TRID Mgmt, Enroll, Payment Credential, Lifecycle Mgmt, Webhooks	Bulk Enrollment
PSP / Enabler	TRID Mgmt, Enroll, Payment Credential, Lifecycle Mgmt, Webhooks	Bulk Enrollment
Wallet	TRID Mgmt, Enroll, Payment Credential, Content Retrieval, Lifecycle Mgmt, Webhooks	Bulk Enrollment

4. Implement real-time token enrollment

Choosing between real-time and bulk provisioning

You can use a combination of both real-time and bulk provisioning methods depending on your use cases. The general guideline for partners is as follows:

If the card is being added or updated by a Cardholder in an interactive flow, use real-time provisioning.
If the card already exists in a secure vault and needs to be upgraded to a network token at scale, use bulk provisioning.

Use the following interactive flows when a cardholder adds or updates a payment method.

Collect card details: PAN, expiration date, CVV, and cardholder name. Then pass these values in your enrollment request using the payment_data object. Use the base64-encode option.
Call: Send a POST request to /v1/payment-tokenization/enrollments with the card details. A 201 response returns the enrollment_id and network_token.
Persist: Keep the enrollment_id and network_token in your card vault. You’ll need both for all subsequent lifecycle and payment credential calls.

Sample request
Sample response (201 Created)

curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-d '{
  "payment_data": "<base64-encoded PAN, expiry, CVV>",
  "reference_account_id": "REFERENCE-ACCOUNT-ID",
  "applicant": {
    "name": { "given_name": "John", "surname": "Doe" },
    "date_of_birth": "1990-01-01",
    "address": {
      "address_line_1": "1 Main St",
      "admin_area_2": "San Jose",
      "admin_area_1": "CA",
      "postal_code": "95131",
      "country_code": "US"
    },
    "email_address": "johndoe@example.com",
    "phone": { "phone_number": { "national_number": "4085551234" } }
  },
  "locale": "en-US",
  "product_name": "COF_MERCHANT",
  "token_requestor": { "id": "<TRID_ID>" },
  "payment_instrument_input_method": "ONFILE"
}'

{
  "enrollment_id": "<ENROLLMENT_ID>",
  "status": "ACTIVE",
  "reuse_type": "NEW",
  "token_info": {
    "id": "<network_token>",
    "expiry_date": "2028-01",
    "tpan_last4": "1234",
    "account_id": "<account_id>",
    "network_token_requestor_id": "<TRID_ID>",
    "issuer_expiry_date": "2028-01",
    "token_assurance_level": "<assurance_level>"
  },
  "metadata": { "...": "..." },
  "issuer_data": { "...": "..." },
  "contents": [ { "...": "content references, such as card art, and terms and conditions" } ],
  "payment_credentials": [],
  "token_requestor": { "id": "<TRID_ID>" },
  "verification_results": { "...": "..." },
  "device_bindings": [],
  "verification_methods": [],
  "risk_decision": "<risk_decision>"
}

Run this full flow end-to-end in the sandbox first with PayPal-provided test cards before moving to a live environment. PayPal sandbox test cards:

Visa: 4622943127025676 (success), 4622943127025673 (ineligible)
Mastercard: 5204731530000000 (success), 5204731530000007 (ineligible)
American Express (Amex): 3717073691911199 (success), 371707369199999 (ineligible)
Discover: Cards starting with 6011000000 (success), Cards starting with 601101000 (PAN ineligible)

Sample request: Retrieve card art/Terms & Conditions
Sample response (200 OK)

Use the content_id values returned in the enrollment response’s contents array to retrieve display assets such as card art:

curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/contents/{content_id}' \
-H 'Authorization: Bearer <ACCESS-TOKEN>'

{
  "content_id": "<content_id>",
  "content_type": "CARD_ART",
  "mime_type": "image/png",
  "width": 600,
  "height": 380,
  "content_cdn_url": "https://<cdn-host>/<path-to-asset>.png"
}

5. Implement bulk enrollment - optional

Use this to asynchronously tokenize large volumes of existing cards-on-file (up to 1,000 for batch).

Submit batch: Send a POST request to /v1/payment-tokenization/batch-requests with a file containing the card details. PP TSP returns a batch_request_id to track the batch.
Listen: PP TSP sends a PAYMENT-TOKENIZATION.BATCH-REQUEST.STATUS-CHANGED webhook when the batch completes or fails.
Retrieve results: Send a GET request to /v1/payment-tokenization/batch-requests/{id}. Append ?fields=ALL only after the batch reaches COMPLETED status to avoid loading partial data.

Sample request: Submit a batch enrollment
Sample response (202 Accepted)

curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/batch-requests' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-H 'PayPal-Request-Id: <idempotency-key>' \
-d '{
  "requests": [
    {
      "bulk_id": "enrollment-1",
      "method": "POST",
      "path": "/v1/payment-tokenization/enrollments",
      "body": {
  "payment_data": "<base64-encoded PAN, expiry, CVV>",
  "reference_account_id": "REFERENCE-ACCOUNT-ID",
  "applicant": {
    "name": { "given_name": "John", "surname": "Doe" },
    "date_of_birth": "1990-01-01",
    "address": {
      "address_line_1": "1 Main St",
      "admin_area_2": "San Jose",
      "admin_area_1": "CA",
      "postal_code": "95131",
      "country_code": "US"
    },
    "email_address": "johndoe@example.com",
    "phone": { "phone_number": { "national_number": "4085551234" } }
  },
  "locale": "en-US",
  "product_name": "COF_MERCHANT",
  "token_requestor": { "id": "<TRID_ID>" },
  "payment_instrument_input_method": "ONFILE"
}
    },
    {
      "bulk_id": "enrollment-2",
      "method": "POST",
      "path": "/v1/payment-tokenization/enrollments",
      "body": {
  "payment_data": "<base64-encoded PAN, expiry, CVV>",
  "reference_account_id": "REFERENCE-ACCOUNT-ID-2",
  "applicant": {
    "name": { "given_name": "John", "surname": "Doe" },
    "date_of_birth": "1990-01-01",
    "address": {
      "address_line_1": "1 Main St",
      "admin_area_2": "San Jose",
      "admin_area_1": "CA",
      "postal_code": "95131",
      "country_code": "US"
    },
    "email_address": "johndoe@example.com",
    "phone": { "phone_number": { "national_number": "4085551234" } }
  },
  "locale": "en-US",
  "product_name": "COF_MERCHANT",
  "token_requestor": { "id": "<TRID_ID>" },
  "payment_instrument_input_method": "ONFILE"
}
    }
  ]
}'

{
  "total_items": 2,
  "details": [
    { "batch_id": "<batch_request_id>", "status": "ACCEPTED" }
  ]
}

Sample request: Get batch status
Sample response

Retrieve the batch tokenization results by sending the following request:

curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/batch-requests/{id}' \
-H 'Authorization: Bearer <ACCESS-TOKEN>'

{
      "total_items": 2,
      "details": [
        {
          "total_batch_items": 2,
          "total_success": 2,
          "batch_id": "11EF-4A21-EE5441F9-A1FB-FA1B92B407D4",
          "status": "COMPLETED",
          "operations": [
            {
              "method": "POST",
              "headers": [],
              "bulk_id": "e5d7b48f-dcd6-4aa7-9cdb-3d77f57c0a37",
              "status": {
                "code": "200"
              },
              "body": {
                "verification_results": [],
                "enrollment_data": [
                  {
                    "token_info": {
                      "id": "2fd1-188667e0-7ab9-46ab-a120-d48d8ff9e3a2",
                      "expiry_date": "2025-12",
                      "tpan_info": "NDg5NTM3MDAxMzM0Njk2Nw==",
                      "tpan_last4": "6967",
                      "account_id": "1234",
                      "network_token_requestor_id": "40010061540"
                    },
                    "metadata": {},
                    "contents": [],
                    "payment_credentials": []
                  }
                ],
                "verification_methods": [],
                "device_bindings": [],
                "lifecycle_reason_details": [],
                "reference_account_id": "CBKM9L56PTL4C",
                "enrollment_id": "8002033245411672066",
                "status": "ACTIVE"
              }
            },
            {
              "method": "POST",
              "headers": [],
              "bulk_id": "95bc1aa6-667f-4572-8254-346d6c4a4705",
              "status": {
                "code": "200"
              },
              "body": {
                "verification_results": [],
                "enrollment_data": [
                  {
                    "token_info": {
                      "id": "2fd1-e497c83f-ebbc-4d8d-ae08-57ada9906928",
                      "expiry_date": "2025-12",
                      "tpan_info": "NDg5NTM3MDAxMzM0NTY3OA==",
                      "tpan_last4": "5678",
                      "account_id": "5678",
                      "network_token_requestor_id": "40010061540"
                    },
                    "metadata": {},
                    "contents": [],
                    "payment_credentials": []
                  }
                ],
                "verification_methods": [],
                "device_bindings": [],
                "lifecycle_reason_details": [],
                "reference_account_id": "CBKM9L56PTL4C",
                "enrollment_id": "8002036407153469914",
                "status": "ACTIVE"
              }
            }
          ]
        }
      ]
    }

Sample request: Get batch details
Sample response

After the batch status is COMPLETED, request full item-level details by sending the following request:

curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/batch-requests/{id}?fields=ALL' \
-H 'Authorization: Bearer <ACCESS-TOKEN>'

{
      "total_items": 2,
      "details": [
        {
          "total_batch_items": 2,
          "total_success": 2,
          "batch_id": "11EF-4A21-EE5441F9-A1FB-FA1B92B407D4",
          "status": "COMPLETED",
          "operations": [
            {
              "method": "POST",
              "headers": [],
              "bulk_id": "e5d7b48f-dcd6-4aa7-9cdb-3d77f57c0a37",
              "status": {
                "code": "200"
              },
              "body": {
                "verification_results": [],
                "enrollment_data": [
                  {
                    "token_info": {
                      "id": "2fd1-188667e0-7ab9-46ab-a120-d48d8ff9e3a2",
                      "expiry_date": "2025-12",
                      "tpan_info": "NDg5NTM3MDAxMzM0Njk2Nw==",
                      "tpan_last4": "6967",
                      "account_id": "1234",
                      "network_token_requestor_id": "40010061540"
                    },
                    "metadata": {},
                    "contents": [],
                    "payment_credentials": []
                  }
                ],
                "verification_methods": [],
                "device_bindings": [],
                "lifecycle_reason_details": [],
                "reference_account_id": "CBKM9L56PTL4C",
                "enrollment_id": "8002033245411672066",
                "status": "ACTIVE"
              }
            },
            {
              "method": "POST",
              "headers": [],
              "bulk_id": "95bc1aa6-667f-4572-8254-346d6c4a4705",
              "status": {
                "code": "200"
              },
              "body": {
                "verification_results": [],
                "enrollment_data": [
                  {
                    "token_info": {
                      "id": "2fd1-e497c83f-ebbc-4d8d-ae08-57ada9906928",
                      "expiry_date": "2025-12",
                      "tpan_info": "NDg5NTM3MDAxMzM0NTY3OA==",
                      "tpan_last4": "5678",
                      "account_id": "5678",
                      "network_token_requestor_id": "40010061540"
                    },
                    "metadata": {},
                    "contents": [],
                    "payment_credentials": []
                  }
                ],
                "verification_methods": [],
                "device_bindings": [],
                "lifecycle_reason_details": [],
                "reference_account_id": "CBKM9L56PTL4C",
                "enrollment_id": "8002036407153469914",
                "status": "ACTIVE"
              }
            }
          ]
        }
      ]
    }

6. Integrate payment credentials into your auth flow

For card-not-present authorizations, call the payment-credentials API to retrieve the network token and cryptogram before constructing the authorization request, then pass these values to your payment processor.

Call: Send a POST request to /v1/payment-tokenization/payment-credentials with token details and transaction data. payment-credentials endpoint supports two modes, fetch and pre-fetch, which you can select through the Prefer: respond-async header. Call just-in-time for Cardholder-Initiated Transaction (CIT) transactions. Cryptograms are single-use and have a limited validity window.
The response returns the network token, cryptogram, and Electronic Commerce Indicator (ECI) needed for authorization. Use these values instead of the original card data when processing the payment.
Pass these fields unchanged into the authorization message to your payment processor. This replaces the raw card number entirely.

Sample request: Fetch, synchronous
Sample request: Prefetch, asynchronous
Sample response

curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/payment-credentials' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-d '{
  "enrollment_id": "<ENROLLMENT_ID>",
  "product_type": "OPEN_LOOP_SINGLE_USE",
  "credential_type": "E_COMMERCE_LONG_FORM",
  "applicant": {
    "email_address": "johndoe@example.com",
    "phone": { "phone_number": { "national_number": "4085551234" } },
    "address": { "...": "billing address" }
  },
  "amount": { "total": { "currency_code": "USD", "value": "49.99" } }
}'

Identical to the synchronous request, plus this header: Prefer: respond-async.

curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/payment-credentials' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-H 'Prefer: respond-async' \
-d '{
  "enrollment_id": "<ENROLLMENT_ID>",
  "product_type": "OPEN_LOOP_SINGLE_USE",
  "credential_type": "E_COMMERCE_LONG_FORM",
  "applicant": {
    "email_address": "johndoe@example.com",
    "phone": { "phone_number": { "national_number": "4085551234" } },
    "address": { "...": "billing address" }
  },
  "amount": { "total": { "currency_code": "USD", "value": "49.99" } }
}'

{
  "token_info": {
    "id": "<network_token>",
    "expiry_date": "2028-01",
    "tpan_info": { "...": "..." },
    "tpan_last4": "1234",
    "account_id": "<account_id>",
    "network_token_requestor_id": "<TRID_ID>",
    "issuer_expiry_date": "2028-01",
    "payment_account_reference": "<PAR>"
  },
  "payment_credentials": [
    {
      "tpan_id": "<tpan_id>",
      "payment_credential_id": "<credential_id>",
      "credential_type": "E_COMMERCE_LONG_FORM",
      "payment_credential_data": "<cryptogram / ECI data>"
    }
  ],
  "links": [ { "...": "..." } ]
}

Sample Account Funding Transaction request
Sample response

curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/payment-credentials' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-d '{
    "credential_type": "E_COMMERCE_LONG_FORM",
    "enrollment_id": "<ENROLLMENT_ID>",
    "amount": {
       "total": {
          "value": "12.00",
          "currency_code": "USD"
       }
    },
    "purchase_context": {"transaction_type":"ACCOUNT_FUND_TRANSFER"},
    "ttl_duration": "PT30M"
}'

{
  "token_info": {
    "id": "<network_token>",
    "expiry_date": "2028-01",
    "tpan_info": { "...": "..." },
    "tpan_last4": "1234",
    "account_id": "<account_id>",
    "network_token_requestor_id": "<TRID_ID>",
    "issuer_expiry_date": "2028-01",
    "payment_account_reference": "<PAR>"
  },
  "payment_credentials": [
    {
      "tpan_id": "<tpan_id>",
      "payment_credential_id": "<credential_id>",
      "credential_type": "E_COMMERCE_LONG_FORM",
      "payment_credential_data": "<cryptogram / ECI data>"
    }
  ],
  "links": [ { "...": "..." } ]
}

7. Handle token lifecycle changes

Lifecycle changes must be mirrored in your vault immediately.

Action	Endpoint
Suspend enrollment, update vault to `SUSPENDED`	`POST /v1/payment-tokenization/enrollments/{id}/suspend`
Reactivate enrollment, update vault to `ACTIVE`	`POST /v1/payment-tokenization/enrollments/{id}/activate`
Close enrollment (network token closed asynchronously)	`POST /v1/payment-tokenization/enrollments/{id}/close`

A suspension only pauses the enrollment. A close is permanent and cannot be undone. It cascades to the underlying network token, which is closed asynchronously. For issuer-initiated changes, such as card reissue, expiration date update, and fraud replacement, PP TSP automatically propagates them and notifies you using PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED or PAYMENT-TOKENIZATION.TOKEN-METADATA.CHANGED webhooks. Process these events to keep your vault in sync.

8. Register and test the webhooks

Subscribe to these webhook events to keep your systems current:

Event	Description	Requirement
`PAYMENT-TOKENIZATION.BATCH-REQUEST.STATUS-CHANGED`	Batch completion/failure	Mandatory
`PAYMENT-TOKENIZATION.TOKEN-METADATA.CHANGED`	Card art, terms and conditions (T&C), or metadata updates	Mandatory
`PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.UPDATED`	Credential changes	Mandatory
`PAYMENT-TOKENIZATION.TOKEN-REQUESTOR.UPDATED`	TRID configuration changes	Mandatory
`PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED`	Token activated, suspended, or closed	Mandatory

Sample webhook payloads

Each event is delivered to your registered endpoint in this envelope:

{
  "status": "200 OK",
  "headers": { "...": "..." },
  "body": {
    "events": [
      {
        "event_type": "<EVENT_NAME>",
        "resource": { "...": "event-specific resource fields" },
        "links": [ { "...": "..." } ]
      }
    ]
  }
}

PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED

{ "event_type": "PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED", "resource": { "enrollment_id": "<enrollment_id>" }, "links": [] }

PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.UPDATED

{ "event_type": "PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.UPDATED", "resource": { "enrollment_id": "<enrollment_id>", "payment_credential_id": "<credential_id>" }, "links": [] }

PAYMENT-TOKENIZATION.TOKEN-METADATA.CHANGED

{ "event_type": "PAYMENT-TOKENIZATION.TOKEN-METADATA.CHANGED", "resource": { "enrollment_id": "<enrollment_id>" }, "links": [] }

PAYMENT-TOKENIZATION.BATCH-REQUEST.STATUS-CHANGED

{ "event_type": "PAYMENT-TOKENIZATION.BATCH-REQUEST.STATUS-CHANGED", "resource": { "batch_id": "<batch_request_id>" }, "links": [] }

PAYMENT-TOKENIZATION.TOKEN-REQUESTOR.UPDATED

{ "event_type": "PAYMENT-TOKENIZATION.TOKEN-REQUESTOR.UPDATED", "resource": { "id": "<trid>" }, "links": [] }

Note: Looking for detailed documentation? A comprehensive Ecommerce Solution Guide, Integration Guide, and API Specification Document are available upon request. The API Specification Document includes sample reference payloads and end-to-end use case examples specific to Ecommerce network tokenization, covering all APIs and common integration scenarios. Reach out to your PayPal Account Representative for the latest documentation.

​Prerequisites

​API reference

​Base URLs

​List of APIs

​Authentication

​Steps for integration

​1. Set up PayPal sandbox environment

​2. Onboard your Token Requestor ID (TRID)

​3. Determine minimum API implementation for your business model

​4. Implement real-time token enrollment

​Choosing between real-time and bulk provisioning

​5. Implement bulk enrollment - optional

​6. Integrate payment credentials into your auth flow

​7. Handle token lifecycle changes

​8. Register and test the webhooks

​Sample webhook payloads