PayPal Provisioning Platform Reference
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:
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.
- | | `CREATE_ACCOUNT_ERROR` | Not applicable | PayPal might be experiencing site issues |
| | `INTERNAL_SERVER_ERROR` | Not applicable | PayPal might be experiencing site issues |
- 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. |