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

## Before you begin

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
* Contact your PayPal account representative to get your sandbox credentials and confirm your TRID model before starting

## Base URL

All paths are prefixed [/v1/payment-tokenization/](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/). Base URLs:

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

| Method | Endpoint                                                       | Purpose                                                              | Recommendation |
| ------ | -------------------------------------------------------------- | -------------------------------------------------------------------- | -------------- |
| POST   | `/v1/payment-tokenization/enrollments`                         | Create a real-time token enrollment for a single card                | **Mandatory**  |
| GET    | `/v1/payment-tokenization/enrollments/{enrollmentId}`          | 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**  |
| 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}/suspend`            | Temporarily suspend a token enrollment                               | Recommended    |
| POST   | `/v1/payment-tokenization/enrollments/{id}/activate`           | Reactivate a previously suspended 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.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

### 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. Authenticate using OAuth 2.0

All API calls require a Bearer token. Obtain one similar to this:

```
POST https://api.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 subsequent requests as `Authorization: Bearer ACCESS-TOKEN`. Tokens typically expire after 8–9 hours — implement caching and refresh logic rather than requesting a new token on every call.

### 3. 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, Amex AETS, Discover DDX).

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

### 4. 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 |

### 5. Implement real-time token enrollment

#### Choosing between real-time and bulk provisioning 

The partners can use a combination of both real-time and bulk provisioning methods depending on their 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.

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)

### 6. 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.

### 7. 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), selectable through the `Prefer: respond-async` header.
  Call just-in-time for CIT transactions; cryptograms are single-use and have a limited validity window.
* The response returns the **network token**, **cryptogram**, and **ECI indicator** 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.

### 8. Handle token lifecycle changes

Lifecycle changes must be mirrored in your vault immediately.

| Action                                                 | Endpoint                          |
| ------------------------------------------------------ | --------------------------------- |
| Suspend enrollment, update vault to `SUSPENDED`        | `POST /enrollments/{id}/suspend`  |
| Reactivate enrollment, update vault to `ACTIVE`        | `POST /enrollments/{id}/activate` |
| Close enrollment (network token closed asynchronously) | `POST /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** (card reissue, expiration date update, fraud replacement, and so on), PP TSP automatically propagates them and notifies you using `PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED` or `PAYMENT-TOKENIZATION.METADATA.CHANGED` webhooks. Process these events to keep your vault in sync.

##### 9. Register and test the webhooks

Subscribe to these webhook events to keep your systems current:

| Event                                               | Description                           | Priority  |
| --------------------------------------------------- | ------------------------------------- | --------- |
| `PAYMENT-TOKENIZATION.BATCH-REQUEST.STATUS-CHANGED` | Batch completion/failure              | Mandatory |
| `PAYMENT-TOKENIZATION.METADATA.CHANGED`             | Card art, 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 |

> **Note:** Looking for detailed documentation?
> A comprehensive E-Commerce 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 e-commerce network tokenization, covering all APIs and common integration scenarios.
> Reach out to your PayPal Account Representative for the latest documentation.