Skip to main content
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/. Base URLs:
EnvironmentURL
Sandboxhttps://api-m.sandbox.paypal.com
Productionhttps://api-m.paypal.com
MethodEndpointPurposeRecommendation
POST/v1/payment-tokenization/enrollmentsCreate a real-time token enrollment for a single cardMandatory
GET/v1/payment-tokenization/enrollments/{enrollmentId}Retrieve enrollment details and token informationMandatory
POST/v1/payment-tokenization/payment-credentialsFetch or pre-fetch a one-time payment cryptogram for a transactionMandatory
POST/v1/payment-tokenization/enrollments/{id}/closePermanently close a token enrollmentMandatory
GET/v1/payment-tokenization/contents/{content_id}Retrieve card art, terms & conditions, or logos for a tokenized cardMandatory
POST/v1/payment-tokenization/batch-requestsSubmit a bulk enrollment batch (up to 1,000 cards)Mandatory
POST/v1/payment-tokenization/token-requestorsCreate and onboard a new Token Requestor (TRID)Recommended
GET/v1/payment-tokenization/token-requestors/{tokenRequestorId}Retrieve TRID configuration, status, and supported networksRecommended
POST/v1/payment-tokenization/search-token-requestorsSearch for TRIDs by name, status, or supported networkRecommended
POST/v1/payment-tokenization/search-enrollmentsSearch enrollments by merchant, partner, token reference, or statusRecommended
POST/v1/payment-tokenization/enrollments/{id}/suspendTemporarily suspend a token enrollmentRecommended
POST/v1/payment-tokenization/enrollments/{id}/activateReactivate a previously suspended enrollmentRecommended

​
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 ModelMust-Have APIsOptional
MerchantTRID Mgmt, Enroll, Payment Credential, Lifecycle Mgmt, WebhooksBulk Enrollment
MarketplaceTRID Mgmt, Enroll, Payment Credential, Lifecycle Mgmt, WebhooksBulk Enrollment
PSP / EnablerTRID Mgmt, Enroll, Payment Credential, Lifecycle Mgmt, WebhooksBulk Enrollment
WalletTRID Mgmt, Enroll, Payment Credential, Content Retrieval, Lifecycle Mgmt, WebhooksBulk 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.
ActionEndpoint
Suspend enrollment, update vault to SUSPENDEDPOST /enrollments/{id}/suspend
Reactivate enrollment, update vault to ACTIVEPOST /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:
EventDescriptionPriority
PAYMENT-TOKENIZATION.BATCH-REQUEST.STATUS-CHANGEDBatch completion/failureMandatory
PAYMENT-TOKENIZATION.METADATA.CHANGEDCard art, T&C, or metadata updatesMandatory
PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.UPDATEDCredential changesMandatory
PAYMENT-TOKENIZATION.TOKEN-REQUESTOR.UPDATEDTRID configuration changesMandatory
PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGEDToken activated, suspended, or closedMandatory
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.