PayPal Provisioning Platform Reference

DOCS

Last updated: Sept 23rd, 7:48pm

Important: PayPal Provisioning Platform is a limited-release solution available only to select partners at this time. For more information, reach out to your PayPal Account Manager.

This section provides links and other information resources to help you integrate the P3 solution.

API References

The PayPal Provisioning Platform solution uses the following APIs:

Linked Instruments

Consumer Referral API

Card Metadata Tags

PayPal Identity calls and token types

Learn more about PayPal Identity calls:

First party call to get access token

Exchange auth code for a refresh token

Exchange refresh token for access token

Learn about the different token types used:

Token type	Expiry period
Authorization code	Three minutes
First-party access token	Eight hours if `grant_type` = `client_credentials`
Third-party access token	15 minutes if `grant_type` = `authorization_code` or `refresh_token`
Referral ID	10 minutes
Refresh token	10 years

Error codes

Learn more about error codes see:

Return URL errors

PayPal generally handles most errors internally. However, in some situations, PayPal might return the user to the merchant's redirect_uri with an error_description and error parameters. This table describes the possible errors:

Error	Error description	Explanation	Recommendation
`RESTRICTED_ACCOUNT`	Not applicable	Possible issue with user account. For assistance, user must contact PayPal.	Notify the user that a problem occurred linking their account. For assistance, user must contact PayPal.
`COUNTRY_NOT_SUPPORTED`	Not applicable	This product is not available in your country.	Contact PayPal for assistance.
`REFERRAL_EXPIRED`	Not applicable	User clicked or was directed to a link that took more than 15 minutes to open.	Relaunch the flow by starting with the referral ID creation.
`SESSION_TIMEOUT`	Not applicable	Too much time spent trying to complete the process or the PayPal configuration was not set up correctly.

If timeout happens during testing, escalate the error to your PayPal account manager.

If this error occurs only once in live PayPal, relaunch the linking flow from the beginning of card selection/referral ID creation.

If you repeatedly run into issues after going live, escalate to your PayPal account manager.

If the error happens during testing, escalate the error to your PayPal account manager.

If this error occurs only once in live PayPal, relaunch the linking flow from the beginning of card selection/referral ID creation.

If you repeatedly run into issues after going live, escalate to your PayPal account manager.

If the error happens during testing, escalate the error to your PayPal account manager.

If live, and one off, relaunch the linking flow from the beginning of card selection/referral ID creation.

If you repeatedly run into issues after going live, escalate to your PayPal account manager.

| | `ACCESS_DENIED`| Consent denied | User clicked the **Not Now** option on the PayPal consent screen. | Notify the user to click **Agree** on the final consent screen to complete the linking flow. Then, prompt the user to restart the process. |

API Errors

Https Status and Name	API	Message	Details
400 Bad Request VALIDATION_ERROR	POST v1/payment-networks/linked-instruments POST /v1/payment-networks/card-accounts/{id}/remove PATCH /v1/payment-networks/card-accounts/{id}	Invalid data provided.	Identifies any kind of input error. `details` contains json path of the error. `"details": [` `{` `"field": "card.accounts.0.account.holder.name",` `"issue": "MISSING_OR_EMPTY"` `},` `{` `"field": "card.accounts.0.expiry.date",` `"issue": "MISSING_OR_EMPTY"` `},` `{` `"field": "card.accounts.0.identifier",` `"issue": "MISSING_OR_EMPTY"` `},` `]` In this sample `expiry_date`, `account.holder.name` and `identifier` are missing.
401 Unauthorized	POST v1/payment-networks/linked-instruments POST /v1/payment-networks/card-accounts/{id}/remove PATCH /v1/payment-networks/card-accounts/{id}	Invalid access token used.	`{` `"error": "invalid_token",` `"error_description": "Access Token not found in cache"` `}`
403 Forbidden NOT_AUTHORIZED	POST v1/payment-networks/linked-instruments POST /v1/payment-networks/card-accounts/{id}/remove PATCH /v1/payment-networks/card-accounts/{id}	Authorization failed due to insufficient permissions.	Partner didn't have right permissions for making this call.
422 Unprocessable Entity	POST /v1/payment-networks/card-accounts/{id}/remove PATCH /v1/payment-networks/card-accounts/{id}
500 Internal Server Error INTERNAL_ERROR	POST v1/payment-networks/linked-instruments POST /v1/payment-networks/card-accounts/{id}/remove PATCH /v1/payment-networks/card-accounts/{id}	An internal server error has occurred.	Internal server error.

Code sample links

The following list provides links to the code samples in this guide.

Item	Description
Partner-initiated flow	Partner-initiated flow with two APIs Partner-initiated flow with one API
PayPal-initiated flow	Redirect user back to partner Link data into PayPal
Add more cards	Add more cards code sample
Encryption	Encryption sample
Add card art	Add card art multipart sample Upload card art Link card to existing art
Lifecycle updates	Lifecycle updates code samples
Webhooks	Add an instrument Update an instrument Remove an instrument Close a wallet

Log values

To assist PayPal support with any issues encountered during the integration, be sure these values are stored:

Value	Description
PayPal-debug-ID	Response header Value that identifies this request used by support.
referral ID	Returned in the Consumer Referral API Response PayPal-generated ID sent to the client in the Consumer Referral API response. The client can send this ID in subsequent API calls and use this ID to determine whether API calls are for the same user’s provisioning flow. A front-end URL parameter also passes this same identifier to PayPal.