NFC Device Tokenization Integration

This guide walks through the end-to-end implementation of NFC Device Tokenization using Secure Credential Services by PayPal.

Prerequisites

To integrate with Secure Credential Services NFC Device Tokenization, you need:

A PayPal business account with a Client ID provisioned for NFC device tokenization
OAuth 2.0 credentials (Client ID and Client Secret)
A Token Requestor ID (TRID), a unique 11-digit identifier obtained via TRID onboarding with the PayPal integration team
A device product configuration and sandbox test card data from your PayPal integration team
Registered HTTPS webhook endpoint for receiving PP TSP event notifications

Note: Contact your PayPal integration team to obtain sandbox OAuth credentials, a device product configuration, and test card data 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	Base 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/devices`	Register an NFC-enabled device	Mandatory
`POST`	`/v1/payment-tokenization/enrollments`	Create a card enrollment (initiate provisioning)	Mandatory
`GET`	`/v1/payment-tokenization/enrollments/{id}`	Retrieve enrollment details and token information	Mandatory
`POST`	`/v1/payment-tokenization/enrollments/{id}/tokens`	Request token digitization from the card network	Mandatory
`GET`	`/v1/payment-tokenization/contents/{content_id}`	Retrieve T&C, card art, or other display assets	Mandatory
`GET`	`/v1/payment-tokenization/enrollments/{id}/identity-verifications`	Get available IDV methods (Yellow Path). Applicable only for Visa cards.	Mandatory
`POST`	`/v1/payment-tokenization/enrollments/{id}/identity-verifications/{idv_id}/deliver`	Deliver the chosen verification method (OTP, etc.)	Mandatory
`POST`	`/v1/payment-tokenization/enrollments/{id}/identity-verifications/{idv_id}/validate`	Validate the user’s verification code	Mandatory
`POST`	`/v1/payment-tokenization/payment-credentials`	Fetch full or dynamic payment credentials	Mandatory
`POST`	`/v1/payment-tokenization/enrollments/{id}/payment-credentials/{cred_id}/acknowledge`	Acknowledge receipt of payment credentials	Mandatory
`POST`	`/v1/payment-tokenization/enrollments/{id}/activate`	Reactivate a suspended enrollment	Recommended
`POST`	`/v1/payment-tokenization/enrollments/{id}/suspend`	Temporarily suspend a token enrollment	Recommended
`POST`	`/v1/payment-tokenization/enrollments/{id}/close`	Permanently close a token enrollment	Mandatory
`GET`	`/v1/payment-tokenization/transactions`	Query transaction history for a token or 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

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

Steps for integration

Complete the following steps to onboard your TRID, register a device, and enroll a card for NFC tokenization. Depending on the card network’s response, enrollment follows either the Green Path, where the card is approved without additional verification, or the Yellow Path, which requires additional identity verification.

1. Complete TRID onboarding

Before initiating any card enrollment, the device partner must complete Token Requestor ID (TRID) onboarding with PayPal TSP. The TRID is a unique 11-digit identifier required in all enrollment and payment credential API calls. Work with your PayPal integration team to complete TRID onboarding and obtain your PP TRID. Include it in the token_requestor.id field of all enrollment and payment credential API requests.

2. Register the device

Device registration is a one-time operation that establishes a trusted device identity with PayPal TSP. The returned device_id is used in all subsequent enrollment calls.

POST /v1/payment-tokenization/devices

On success, PP TSP returns a unique device_id. Store this securely and include it in all subsequent card enrollment requests. Do not re-register the same device.

Sample request
Sample response

curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/devices' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-d '{
  "device_info": {
    "external_device_id": "04a4bbce-1d03-4bbc-aa21-1b6a22afee01",
    "device_type": "WEARABLE",
    "extended_device_data": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
  },
  "certificates": {
    "device_certificates": [
      { "certificate_usage": "CONFIDENTIALITY", "certificate_format": "X509", "certificate_value": "28 A3 49 78 FA 12 37 44 81 B7 C3 93 C1 ..." },
      { "certificate_usage": "INTEGRITY", "certificate_format": "X509", "certificate_value": "78 A3 44 21 1A 22 47 B8 B1 B7 C3 32 45 ..." },
      { "certificate_usage": "DEVICE_ROOT", "certificate_format": "X509", "certificate_value": "22 A4 54 81 FA 28 34 BB C2 A1 28 28 12 ..." }
    ]
  },
  "wallet_id": "0esfiuy197akh091nq93j383uj8js",
  "product_name": "PPWALLET_NFC_TOKEN_PROVIDER"
}'

{
  "device_id": "<device_id>",
  "external_device_id": "04a4bbce-1d03-4bbc-aa21-1b6a22afee01",
  "status": "ACTIVE",
  "links": [
    { "rel": "self", "method": "GET", "href": ".../v1/payment-tokenization/devices/<device_id>" },
    { "rel": "enrollments", "method": "POST", "href": ".../v1/payment-tokenization/devices/<device_id>/enrollments" }
  ]
}

3. Enroll a card (Green Path)

The Green Path is the standard provisioning flow where a card is approved for tokenization without additional user identity verification.

3a. Create enrollment

After the user authenticates and selects a card, submit the enrollment request with encrypted card details:

POST /v1/payment-tokenization/enrollments

PP TSP checks card eligibility with the card network and returns an enrollment_id, a Terms & Conditions (T&C) ID, and an initial enrollment status of PENDING_TOKEN_CREATION.

Sample request
Sample response

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 card details>",
  "locale": "en-US",
  "product_name": "PPWALLET_DEVICE_TOKEN",
  "token_requestor": { "id": "<TRID_ID>" },
  "device_info": { "device_id": "656E5DYUS6EQL" },
  "payment_instrument_input_method": "MANUAL"
}'

{
  "enrollment_id": "<ENROLLMENT_ID>",
  "status": "PENDING_TOKEN_CREATION",
  "enrollment_data": {
    "contents": [
      { "content_id": "<content_id>", "content_type": "TERMS_AND_CONDITIONS" }
    ]
  },
  "links": [
    { "rel": "self", "method": "GET", "href": ".../v1/payment-tokenization/enrollments/<ENROLLMENT_ID>" }
  ]
}

3b. Retrieve and display T&C, card art, and other assets

GET /v1/payment-tokenization/contents/{content_id}

Retrieve the T&C and other content and display it to the user. Capture explicit user consent before proceeding.

Sample request
Sample response

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":"256",
   "height":"256",
   "content_cdn_url":"<URL>"
}

3c. Tokenize the card

POST /v1/payment-tokenization/enrollments/{id}/tokens

PP TSP requests token digitization from the card network. The network responds with a Token Unique Reference (TUR), token details, and an initial token status: either ACTIVE, PENDING_TOKEN_ACTIVATION, or PENDING_VERIFICATION_REQUIRED. If the token is not immediately active, PayPal TSP will send a PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED notification when the token is activated. PayPal TSP sends a PAYMENT-TOKENIZATION.ENROLLMENT.CREATED webhook followed by a PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.CREATED webhook once credentials are provisioned.

Sample request
Sample response: 201 Created

curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments/<ENROLLMENT_ID>/tokens' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-d '{
   "token_info":{
      "tsp_info":{
         "type":"VTS",
         "network_enrollment_id":"58efa5580d5646a0d7cc1162f205b302"
      },
      "wallet_provider_info":{
         "enrollment_id":"71bb9617b76614ed0b871bf4177a5302",
         "name":"THALES",
         "product_id":"VTSMOCK_Pay_001",
         "product_name":"Visa Card"
      },
      "payment_account_reference":"<REF_ID>",
      "expiry_date":"2027-12",
      "tpan_last4":"9747",
      "issuer_expiry_date":"2026-12",
      "account_id":"2432"
   },
   "metadata":{
      "long_description":"Visa Card",
      "short_description":"Visa Card"
   },
   "issuer_data":{
      "name":"Visa Test",
      "email":"visatest_02@visa.com",
      "toc_url":"https://terms.html"
   }
}'

{
   "enrollment":{
      "enrollment_id":"<ENROLLMENT_ID>",
      "status":"ACTIVE",
      "enrollment_data":[
         {
            "token_info":{
               "id":"<TOKEN_ID>",
               "tpan_last4":"9747",
               "issuer_expiry_date":"2026-12",
               "account_id":"2432",
               "issuing_country_code":"US",
               "payment_account_reference":"<REF_ID>",
               "tsp_info":{
                  "type":"VTS",
                  "network_enrollment_id":"58efa5580d5646a0d7cc1162f205b302"
               }
            }
         }
      ]
   },
   "idv_decision":"APPROVED"
}

4. Enroll a card (Yellow Path)

The Yellow Path extends the Green Path when the card network requires additional identity verification (IDV) before activating the token.

4a. Get verification methods

GET /v1/payment-tokenization/enrollments/{id}/identity-verifications

Returns available IDV methods such as SMS OTP, email, and app-to-app. Present these options to the user.

Sample request
Sample response: 200 OK

curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments/<ENROLLMENT_ID>/identity-verifications' \
-H 'Authorization: Bearer <ACCESS-TOKEN>'

{
   "verification_methods":[
      {
         "id":"idv-method-sms-001",
         "method_type":"SMS",
         "value":"+1-XXX-XXX-7890"
      },
      {
         "id":"idv-method-email-002",
         "method_type":"EMAIL",
         "value":"u***r@example.com"
      }
   ],
   "links":[
      {
         "rel":"self",
         "method":"GET",
         "href":"https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments/<ENROLLMENT_ID>/identity-verifications"
      },
      {
         "rel":"deliver",
         "method":"POST",
         "href":"https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments/<ENROLLMENT_ID>/identity-verifications/idv-method-sms-001/deliver"
      }
   ]
}

4b. Submit verification

POST /v1/payment-tokenization/enrollments/{id}/identity-verifications/{idv_id}/deliver

PP TSP forwards the IDV delivery request to the card network. The response includes OTP expiry details.

Sample request
Sample response

curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments/<ENROLLMENT_ID>/identity-verifications/idv-method-sms-001/deliver' \
-H 'Authorization: Bearer <ACCESS-TOKEN>'

{
   "otp_expiration_time":"2026-05-12T10:30:00Z",
   "max_otp_retries":3,
   "max_new_otp_requests":5,
   "links":[
      {
         "rel":"validate",
         "method":"POST",
         "href":"https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments/<ENROLLMENT_ID>/identity-verifications/idv-method-sms-001/validate"
      }
   ]
}

4c. Validate OTP

POST /v1/payment-tokenization/enrollments/{id}/identity-verifications/{idv_id}/validate

Submit the user’s OTP. Returns HTTP 204 on success. After successful IDV, the card network sends a provisioning notification to PP TSP, which caches the credentials and sends a PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.CREATED webhook.

Sample request
Sample response

curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments/<ENROLLMENT_ID>/identity-verifications/idv-method-sms-001/validate' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
    "idv_code": "457291",
    "idv_code_type": "ONE_TIME_PASSCODE"
}'

204 No Content

5. Fetch payment credentials

After receiving the PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.CREATED webhook, fetch and acknowledge payment credentials. Repeat this step whenever the device’s credential cache needs replenishing.

5a. Retrieve enrollment and credential details

Confirm the enrollment state and retrieve the payment credential metadata:

GET /v1/payment-tokenization/enrollments/{id}

Use the enrollment_id and payment_credential_id from the webhook payload. Skip this step when replenishing an existing enrollment: you already have this context from the initial fetch.

5b. Fetch credentials

After receiving the PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.CREATED webhook, fetch the full encrypted credentials:

POST /v1/payment-tokenization/payment-credentials

Set credential_type based on what the device needs:

Credential Type	Description	When to Use
`TOKEN_CREDENTIAL_FULL`	A complete set of credentials loaded from PP TSP’s secure cache. No network call required.	Initial provisioning or when a full credential set is needed.
`TOKEN_CREDENTIAL_DYNAMIC`	A fresh, single-use credential generated by the card network in response to a replenishment request.	When the device’s credential cache is running low or after credentials are exhausted.

Sample 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 '{
   "enrollment_id":"<ENROLLMENT_ID>",
   "credential_type":"TOKEN_CREDENTIAL_FULL",
   "device_info":{
      "device_id":"947c4425-5c65-4417-9c35-f87af665a95c",
      "device_type":"WEARABLE"
   }
}'

{
   "token_info":{
      "id":"<TOKEN_ID>",
      "expiry_date":"2027-12",
      "tpan_info":"<BASE 64 encoded TPAN_INFO>",
      "tpan_last4":"5272",
      "account_id":"1183",
      "payment_account_reference":"50016DHAIAOOEA7BU7PVVJLHBFVZ0"
   },
   "payment_credentials":[
      {
         "tpan_id":"2fab-9f1e7d5c-1429-40d5-beec-16d26fa80a39",
         "payment_credential_id":"11EF-F3C0-7AFC4CE1-902A-72144E2C9AAC",
         "credential_type":"TOKEN_CREDENTIAL_FULL",
         "network_type":"MASTERCARD",
         "payment_credential_data":"Base 64 encoded credential data"
      }
   ]
}

PP TSP returns encrypted credential data secured using device certifications.

5c. Acknowledge receipt

After the device successfully receives and stores the full credentials, acknowledge receipt:

POST /v1/payment-tokenization/enrollments/{id}/payment-credentials/{cred_id}/acknowledge

PP TSP uses this acknowledgment to notify the card network of the successful provisioning outcome. Repeat 5b and 5c whenever the device needs a dynamic credential.

Sample request
Sample response

curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments/<ENROLLMENT_ID>/payment-credentials/<PC_ID>/acknowledge' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-d '{
    "provisioning_status": "SUCCESS",
    "credential_type": "TOKEN_CREDENTIAL_FULL"
}'

204 No Content

6. Handle token lifecycle events

PP TSP automatically keeps tokens synchronized with underlying card state. Use the following endpoints for partner-initiated operations:

Scenario	Action	Endpoint
User removes a card from the device	Close enrollment (irreversible)	`POST /v1/payment-tokenization/enrollments/{id}/close`
Device is lost or stolen	Suspend enrollment	`POST /v1/payment-tokenization/enrollments/{id}/suspend`
Device is recovered	Reactivate enrollment	`POST /v1/payment-tokenization/enrollments/{id}/activate`

For issuer- or network-initiated changes such as card reissue, fraud replacement, or loss/theft, PP TSP processes the update and notifies Wallet Server via a PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED webhook. Call GET enrollment to retrieve the updated state and take appropriate action. Closing an enrollment is irreversible: PP TSP sends a delete request to the card network and the token is permanently deactivated. Use suspend for temporary disabling.

7. Register and handle webhooks

PP TSP publishes signed webhook events to your registered HTTPS endpoint whenever a significant event occurs. Subscribe to all events below and return HTTP 200 to acknowledge receipt. PP TSP retries delivery for unacknowledged events. Set up idempotent handlers to handle duplicate deliveries safely.

Event	Trigger	Required action	Requirement
`PAYMENT-TOKENIZATION.ENROLLMENT.CREATED`	A card enrollment has been successfully created and the token is provisioned by the card network.	Store the `enrollment_id` and `device_id` from the payload. Proceed to fetch payment credentials.	Mandatory
`PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.CREATED`	PP TSP has cached a new set of encrypted payment credentials and they are ready to be fetched by Wallet Server.	Call the Fetch Payment Credentials endpoint using the `enrollment_id` in the event payload, then acknowledge receipt.	Mandatory
`PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.UPDATED`	An existing payment credential has been updated: for example, following a token reissue or credential refresh by the card network.	Discard the outdated credential on the device and fetch the updated credential set. Re-acknowledge after delivery.	Mandatory
`PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED`	The token status has changed: either partner-initiated (activate, suspend, close) or issuer/network-initiated (card reissue, fraud replacement, loss/theft).	Call `GET /enrollments/{id}` to retrieve the current status. Update your local vault and surface the new state to the user, such as disabling tap-to-pay if `SUSPENDED` or `CLOSED`.	Mandatory
`PAYMENT-TOKENIZATION.TOKEN-METADATA.CHANGED`	Token metadata has been updated: for example, card art, Terms & Conditions, or other display assets associated with the token have changed.	Re-fetch the relevant content using the `content_id` values in the event payload. Re-display updated T&C to the user if required and capture fresh consent.	Mandatory
`PAYMENT-TOKENIZATION.TRANSACTION.CREATED`	An NFC tap-to-pay transaction has been processed against a token managed by PP TSP.	Log the transaction details for reconciliation, display transaction history to the user, and trigger any downstream notifications or replenishment flows as needed.	Mandatory

Note: PP TSP signs all webhook payloads. Always verify the signature before processing the event. Never process an event from an unverified source.

Sample webhook payloads Each event is delivered to your registered endpoint in the following envelope:

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

PAYMENT-TOKENIZATION.ENROLLMENT.CREATED

{ "event_type": "PAYMENT-TOKENIZATION.ENROLLMENT.CREATED", "resource": { "enrollment_id": "<enrollment_id>", "device_id": "<device_id>" }, "links": [] }

PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.CREATED

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

PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.UPDATED

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

PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED

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

PAYMENT-TOKENIZATION.TOKEN-METADATA.CHANGED

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

PAYMENT-TOKENIZATION.TRANSACTION.CREATED

{ "event_type": "PAYMENT-TOKENIZATION.TRANSACTION.CREATED", "resource": { "enrollment_id": "<enrollment_id>" }, "links": [] }

Testing and go-live checklist

Complete the following in your sandbox environment before moving to production.

Credentials and setup: Obtain sandbox OAuth credentials, test device configuration, and test card data from the PayPal integration team. Confirm OAuth token acquisition and refresh logic.
TRID onboarding: Complete TRID onboarding and verify your PP TRID is included in all enrollment and credential requests.
Device registration: Confirm device registration returns a valid device_id with ACTIVE status.
Green Path enrollment: Complete an end-to-end Green Path enrollment with ACTIVE status confirmed.
Yellow Path enrollment: Complete an end-to-end Yellow Path enrollment including all IDV steps.
Payment credentials: Test both Full and Dynamic credential fetch and acknowledgment successfully.
Lifecycle management: Test activate, suspend, and close operations via API.
Webhooks: Verify all webhook event types are delivered and processed correctly in sandbox.
Security: Confirm no raw PAN data appears in logs, responses, or stored records.
Go-live: Contact your PayPal integration team to confirm production credentials, TRIDs, and webhook endpoints are configured separately from sandbox.

​Prerequisites

​API reference

​Base URLs

​List of APIs

​Authentication

​Steps for integration

​1. Complete TRID onboarding

​2. Register the device

​3. Enroll a card (Green Path)

​3a. Create enrollment

​3b. Retrieve and display T&C, card art, and other assets

​3c. Tokenize the card

​4. Enroll a card (Yellow Path)

​4a. Get verification methods

​4b. Submit verification

​4c. Validate OTP

​5. Fetch payment credentials

​5a. Retrieve enrollment and credential details

​5b. Fetch credentials

​5c. Acknowledge receipt

​6. Handle token lifecycle events

​7. Register and handle webhooks

​Testing and go-live checklist