> ## 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. # 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/`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/). 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`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/registerdevice) | Register an NFC-enabled device | **Mandatory** | | `POST` | [`/v1/payment-tokenization/enrollments`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/enrollment-decision) | Create a card enrollment (initiate provisioning) | **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/enrollments/{id}/tokens`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/token-creation) | Request token digitization from the card network | **Mandatory** | | `GET` | [`/v1/payment-tokenization/contents/{content_id}`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/get-content) | 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`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/deliver-idv) | Deliver the chosen verification method (OTP, etc.) | **Mandatory** | | `POST` | [`/v1/payment-tokenization/enrollments/{id}/identity-verifications/{idv_id}/validate`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/validate-idv) | Validate the user's verification code | **Mandatory** | | `POST` | [`/v1/payment-tokenization/payment-credentials`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/token-provisioning) | Fetch full or dynamic payment credentials | **Mandatory** | | `POST` | [`/v1/payment-tokenization/enrollments/{id}/payment-credentials/{cred_id}/acknowledge`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/acknowledge-payment-credentials) | Acknowledge receipt of payment credentials | **Mandatory** | | `POST` | [`/v1/payment-tokenization/enrollments/{id}/activate`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/token-activate) | Reactivate a 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 | | `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/transactions`](https://developer.paypal.com/api/limited-release/payment-tokenization/v1/get-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 Content-Type: application/x-www-form-urlencoded grant_type=client_credentials # Pass the token in every request Authorization: Bearer ``` 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. ``` curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/devices' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -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": "", "external_device_id": "04a4bbce-1d03-4bbc-aa21-1b6a22afee01", "status": "ACTIVE", "links": [ { "rel": "self", "method": "GET", "href": ".../v1/payment-tokenization/devices/" }, { "rel": "enrollments", "method": "POST", "href": ".../v1/payment-tokenization/devices//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`. ``` curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{ "payment_data": "", "locale": "en-US", "product_name": "PPWALLET_DEVICE_TOKEN", "token_requestor": { "id": "" }, "device_info": { "device_id": "656E5DYUS6EQL" }, "payment_instrument_input_method": "MANUAL" }' ``` ``` { "enrollment_id": "", "status": "PENDING_TOKEN_CREATION", "enrollment_data": { "contents": [ { "content_id": "", "content_type": "TERMS_AND_CONDITIONS" } ] }, "links": [ { "rel": "self", "method": "GET", "href": ".../v1/payment-tokenization/enrollments/" } ] } ``` #### 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. ``` curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/contents/{CONTENT_ID}' \ -H 'Authorization: Bearer ' ``` ``` { "content_id":"", "content_type":"CARD_ART", "mime_type":"image/png", "width":"256", "height":"256", "content_cdn_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. ``` curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments//tokens' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -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":"", "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":"", "status":"ACTIVE", "enrollment_data":[ { "token_info":{ "id":"", "tpan_last4":"9747", "issuer_expiry_date":"2026-12", "account_id":"2432", "issuing_country_code":"US", "payment_account_reference":"", "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. ``` curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments//identity-verifications' \ -H 'Authorization: Bearer ' ``` ``` { "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//identity-verifications" }, { "rel":"deliver", "method":"POST", "href":"https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments//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. ``` curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments//identity-verifications/idv-method-sms-001/deliver' \ -H 'Authorization: Bearer ' ``` ``` { "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//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. ``` curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments//identity-verifications/idv-method-sms-001/validate' \ -H 'Authorization: Bearer ' \ -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. | ``` curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/payment-credentials' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -d '{ "enrollment_id":"", "credential_type":"TOKEN_CREDENTIAL_FULL", "device_info":{ "device_id":"947c4425-5c65-4417-9c35-f87af665a95c", "device_type":"WEARABLE" } }' ``` ``` { "token_info":{ "id":"", "expiry_date":"2027-12", "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. ``` curl -L 'https://api-m.sandbox.paypal.com/v1/payment-tokenization/enrollments//payment-credentials//acknowledge' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -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": "", "resource": { "...": "event-specific resource fields" }, "links": [ { "...": "..." } ] } ] } } ``` `PAYMENT-TOKENIZATION.ENROLLMENT.CREATED` ``` { "event_type": "PAYMENT-TOKENIZATION.ENROLLMENT.CREATED", "resource": { "enrollment_id": "", "device_id": "" }, "links": [] } ``` `PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.CREATED` ``` { "event_type": "PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.CREATED", "resource": { "enrollment_id": "", "device_id": "", "payment_credential_id": "" }, "links": [] } ``` `PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.UPDATED` ``` { "event_type": "PAYMENT-TOKENIZATION.PAYMENT-CREDENTIAL.UPDATED", "resource": { "enrollment_id": "", "payment_credential_id": "" }, "links": [] } ``` `PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED` ``` { "event_type": "PAYMENT-TOKENIZATION.TOKEN-STATUS.CHANGED", "resource": { "enrollment_id": ""}, "links": [] } ``` `PAYMENT-TOKENIZATION.TOKEN-METADATA.CHANGED` ``` { "event_type": "PAYMENT-TOKENIZATION.TOKEN-METADATA.CHANGED", "resource": { "enrollment_id": ""}, "links": [] } ``` `PAYMENT-TOKENIZATION.TRANSACTION.CREATED` ``` { "event_type": "PAYMENT-TOKENIZATION.TRANSACTION.CREATED", "resource": { "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.