PayPal Provisioning Platform Reference

DOCS

Last updated: Sept 23rd, 7:48pm

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:

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.
    • | | `CREATE_ACCOUNT_ERROR` | Not applicable | PayPal might be experiencing site issues |
      • 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.

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

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.

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more