> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration

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/`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/). 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`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/enrollment-decision)          | Create a real-time token enrollment for a single card                | **Mandatory** |
| `GET`  | [`/v1/payment-tokenization/enrollments/{id}`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/enrollment-status)       | Retrieve enrollment details and token information                    | **Mandatory** |
| `POST` | [`/v1/payment-tokenization/payment-credentials`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/token-provisioning)   | Fetch or pre-fetch a one-time payment cryptogram for a transaction   | **Mandatory** |
| `POST` | [`/v1/payment-tokenization/enrollments/{id}/close`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/token-close)       | Permanently close a token enrollment                                 | **Mandatory** |
| `GET`  | [`/v1/payment-tokenization/contents/{content_id}`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/get-content)        | Retrieve card art, terms & conditions, or logos for a tokenized card | **Mandatory** |
| `POST` | [`/v1/payment-tokenization/batch-requests`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/batch-post)                | Submit a bulk enrollment batch (up to 1,000 cards)                   | **Mandatory** |
| `GET`  | [`/v1/payment-tokenization/batch-requests/{id}`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/batch-get)            | 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`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/list-enrollments)      | Search enrollments by merchant, partner, token reference, or status  | Recommended   |
| `POST` | [`/v1/payment-tokenization/enrollments/{id}/activate`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/token-activate) | Reactivate a previously suspended enrollment                         | Recommended   |
| `POST` | [`/v1/payment-tokenization/enrollments/{id}/suspend`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/token-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.

<Tabs>
  <Tab title="Sample request">
    ```bash theme={null}
    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"
    }'
    ```
  </Tab>

  <Tab title="Sample response (201 Created)">
    ```json theme={null}
    {
      "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": []
            }
          ]
        }
      ]
    }
    ```
  </Tab>
</Tabs>

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`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/enrollment-decision) 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.

<Tabs>
  <Tab title="Sample request">
    ```bash theme={null}
    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"
    }'
    ```
  </Tab>

  <Tab title="Sample response (201 Created)">
    ```json theme={null}
    {
      "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>"
    }
    ```
  </Tab>
</Tabs>

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)

<Tabs>
  <Tab title="Sample request: Retrieve card art/Terms & Conditions">
    Use the `content_id` values returned in the enrollment response's contents array to retrieve display assets such as card art:

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

  <Tab title="Sample response (200 OK)">
    ```json theme={null}
    {
      "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"
    }
    ```
  </Tab>
</Tabs>

### 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`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/batch-post) 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}`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/batch-get). Append `?fields=ALL` only after the batch reaches `COMPLETED` status to avoid loading partial data.

<Tabs>
  <Tab title="Sample request: Submit a batch enrollment">
    ```bash theme={null}
    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"
    }
        }
      ]
    }'
    ```
  </Tab>

  <Tab title="Sample response (202 Accepted)">
    ```json theme={null}
    {
      "total_items": 2,
      "details": [
        { "batch_id": "<batch_request_id>", "status": "ACCEPTED" }
      ]
    }
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Sample request: Get batch status">
    Retrieve the batch tokenization results by sending the following request:

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

  <Tab title="Sample response">
    ```json theme={null}
    {
          "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"
                  }
                }
              ]
            }
          ]
        }
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Sample request: Get batch details">
    After the batch status is `COMPLETED`, request full item-level details by sending the following request:

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

  <Tab title="Sample response">
    ```json theme={null}
    {
          "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"
                  }
                }
              ]
            }
          ]
        }
    ```
  </Tab>
</Tabs>

### 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`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/token-provisioning) 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.

<Tabs>
  <Tab title="Sample request: Fetch, synchronous">
    ```bash theme={null}
    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" } }
    }'
    ```
  </Tab>

  <Tab title="Sample request: Prefetch, asynchronous">
    Identical to the synchronous request, plus this header: `Prefer: respond-async`.

    ```bash theme={null}
    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" } }
    }'
    ```
  </Tab>

  <Tab title="Sample response">
    ```json theme={null}
    {
      "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": [ { "...": "..." } ]
    }
    ```
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Sample Account Funding Transaction request">
    ```bash theme={null}
    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"
    }'
    ```
  </Tab>

  <Tab title="Sample response">
    ```json theme={null}
    {
      "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": [ { "...": "..." } ]
    }
    ```
  </Tab>
</Tabs>

### 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:

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

`PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED`

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

`PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.UPDATED`

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

`PAYMENT-TOKENIZATION.TOKEN-METADATA.CHANGED`

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

`PAYMENT-TOKENIZATION.BATCH-REQUEST.STATUS-CHANGED`

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

`PAYMENT-TOKENIZATION.TOKEN-REQUESTOR.UPDATED`

```json theme={null}
{ "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.