Create onboarding credentials

Before you can embed PayPal's merchant onboarding flow, create the required partner referral URL and client token to initialize the Partner SDK.

Create partner referral URL

Use a valid access token and send a POST request to /v2/customer/partner-referrals with all required request parameters including operations, products, legal_consents, organization, and tracking_id. On successful creation, PayPal returns an URL for merchant onboarding that you'll use to initialize the SDK.

curl --location --request POST 'https://api-m.sandbox.paypal.com/v2/customer/partner-referrals' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "operations": [
        {
            "operation": "API_INTEGRATION",
            "api_integration_preference": {
                "rest_api_integration": {
                    "integration_method": "SDK",
                    "integration_type": "THIRD_PARTY",
                    "third_party_details": {
                        "signup_mode": "VERIFY_WITH_PAYPAL",
                        "organization": "ORGANIZATION"
                    }
                }
            }
        }
    ],
    "products": [
        "PPCP"
    ],
    "legal_consents": [
        {
            "type": "SHARE_DATA_CONSENT",
            "granted": true
        }
    ],
    "legal_country_code": "US",
    "tracking_id": "TRACKING_ID"
}'

Request and response parameters

Select a tab to view either the required request parameters or the expected response parameters for order creation.

Parameter name, Description
Parameter name	Description
`operations` Required, array	Operations to perform for the customer while they share their data. For Embedded integration, set to `API_INTEGRATION` with SDK integration method.
`operations.operation` Required, string	The operation to enable for the customer. Set to `API_INTEGRATION` to enable API permissions required for integration.
`operations.api_integration_preference` object	The integration details for the partner and customer relationship. Required when operation is `API_INTEGRATION`. Replace `ORGANIZATION` with the value provided by PayPal.
`products` Required, array	An array of PayPal products to which the partner wants to onboard the customer. Set to `PPCP` for PayPal Complete Payments.
`legal_consents` Required, array	An array of all consents that the partner has received from this merchant. If `SHARE_DATA_CONSENT` is not granted, PayPal does not store customer data.
`legal_country_code string`	Legal Country Code. For example, `US`.
`tracking_id` string	The partner's unique identifier for this merchant in their system.

Note: This section documents only a subset of relevant request and response parameters. For the exhaustive list of request parameters, see API reference.

Note: If you send a GET request to /v2/customer/partner-referrals/{partner_referral_id}, the response returns the data you submitted for the merchant. It doesn't return any data that the merchant entered during the PayPal onboarding process.

Create client token

The client token is a browser-safe token that authorizes your app to use the Partner SDK. To obtain this token, call PayPal's OAuth API from your server and use the access_token from the response to initialize the SDK.

For the server-side call to the /v1/oauth2/token endpoint:

Encode your app credentials (Client ID and Secret) in Base64 format and include them in the Authorization header.
Include the following data parameters:
- grant_type: Set to client_credentials to specify that the app is requesting to exchange the client ID and secret for an access token.
- response_type: Set to client_token to request a client-side access token.
- domains[]: Specify your root domain(s) where the Partner SDK will be used. Do not include subdomains, wildcards, or protocols.
- intent: Set to sdk_init to specify that the request is for Partner SDK initialization.
Replace CLIENT_ID with your client ID and CLIENT_SECRET with your client secret in the Authorization header. To get your client ID and secret, see Get your client credentials.

Response: Contains the browser-safe client token in the access_token parameter.

curl --location --request POST 'https://api-m.sandbox.paypal.com/v1/oauth2/token' \
--header 'Authorization: Basic base64encode(CLIENT_ID:CLIENT_SECRET)' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'response_type=client_token' \
--data-urlencode 'domains[]=example.com' \
--data-urlencode 'intent=sdk_init'

Important information

Security and usage:

Use a server-side call to generate a CLIENT_TOKEN, then pass the token into the Partner SDK.
Note: The client token is different from a standard access token. Client tokens are safe for client-side use, while access tokens must remain on the server.

Validation:

A successful request results in an HTTP 200 Success status code.
Ensure that the access_token field starts with eyJraW…, which indicates that you've created a client token. If it starts with A21_A..., this is an access token and must not be passed to the client side.

Token properties:

Client tokens expire after 15 minutes.
Use the access_token value from the response as the CLIENT_TOKEN when initializing the Partner SDK.

Create partner referral URL

curl --location --request POST 'https://api-m.sandbox.paypal.com/v2/customer/partner-referrals' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "operations": [
        {
            "operation": "API_INTEGRATION",
            "api_integration_preference": {
                "rest_api_integration": {
                    "integration_method": "SDK",
                    "integration_type": "THIRD_PARTY",
                    "third_party_details": {
                        "signup_mode": "VERIFY_WITH_PAYPAL",
                        "organization": "ORGANIZATION"
                    }
                }
            }
        }
    ],
    "products": [
        "PPCP"
    ],
    "legal_consents": [
        {
            "type": "SHARE_DATA_CONSENT",
            "granted": true
        }
    ],
    "legal_country_code": "US",
    "tracking_id": "TRACKING_ID"
}'

Parameter name

Description

operations
Required, array

Operations to perform for the customer while they share their data.

For Embedded integration, set to API_INTEGRATION with SDK integration method.

operations.operation
Required, string

The operation to enable for the customer. Set to API_INTEGRATION to enable API permissions required for integration.

operations.api_integration_preference
object

The integration details for the partner and customer relationship. Required when operation is API_INTEGRATION. Replace ORGANIZATION with the value provided by PayPal.

products
Required, array

An array of PayPal products to which the partner wants to onboard the customer. Set to PPCP for PayPal Complete Payments.

legal_consents
Required, array

An array of all consents that the partner has received from this merchant. If SHARE_DATA_CONSENT is not granted, PayPal does not store customer data.

legal_country_code string

Legal Country Code. For example, US.

tracking_id
string

The partner's unique identifier for this merchant in their system.

Create client token

For the server-side call to the /v1/oauth2/token endpoint:

Encode your app credentials (Client ID and Secret) in Base64 format and include them in the Authorization header.
Include the following data parameters:
- grant_type: Set to client_credentials to specify that the app is requesting to exchange the client ID and secret for an access token.
- response_type: Set to client_token to request a client-side access token.
- domains[]: Specify your root domain(s) where the Partner SDK will be used. Do not include subdomains, wildcards, or protocols.
- intent: Set to sdk_init to specify that the request is for Partner SDK initialization.
Replace CLIENT_ID with your client ID and CLIENT_SECRET with your client secret in the Authorization header. To get your client ID and secret, see Get your client credentials.

Response: Contains the browser-safe client token in the access_token parameter.

curl --location --request POST 'https://api-m.sandbox.paypal.com/v1/oauth2/token' \
--header 'Authorization: Basic base64encode(CLIENT_ID:CLIENT_SECRET)' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'response_type=client_token' \
--data-urlencode 'domains[]=example.com' \
--data-urlencode 'intent=sdk_init'

Security and usage:

Use a server-side call to generate a CLIENT_TOKEN, then pass the token into the Partner SDK.
Note: The client token is different from a standard access token. Client tokens are safe for client-side use, while access tokens must remain on the server.

Validation:

A successful request results in an HTTP 200 Success status code.
Ensure that the access_token field starts with eyJraW…, which indicates that you've created a client token. If it starts with A21_A..., this is an access token and must not be passed to the client side.

Token properties:

Client tokens expire after 15 minutes.
Use the access_token value from the response as the CLIENT_TOKEN when initializing the Partner SDK.

Create onboarding credentials

Create partner referral URL

Request and response parameters

Create client token

Important information

On this page

On this page

On this page

Create onboarding credentials

Create partner referral URL

Request and response parameters

Create client token

Important information

On this page

On this page

Create onboarding credentials

On this page

On this page

On this page

We currently use cookies to improve and customize your experience on our site. If you accept, we’ll also use marketing cookies to show you personalized ads. Manage your cookies and learn more.

Create onboarding credentials

On this page

On this page