The PayPal Provisioning Platform (P3) offers a new, improved, and efficient way for a partner to integrate with PayPal to enable financial instrument sharing and streamline the customer's experience of the partner's app. In addition, P3 offers:

The ability to build partner-initiated (push) and PayPal-initiated (pull) integration flows at the same time

User-profile sharing using the Consumer Referral API interface

Separated financial instrument (Card/Bank/ACH) data can be sent using a new Linked Instrument API interface instead of using the legacy Add Card API

New Lifecycle Update APIs

Expanded Webhooks notifications for instrument creation/failure and lifecycle updates

A new interface for uploading Card Art

Optional PAN encryption in the payload

Expanded developer portal documentation

Can I continue to use the legacy client id for PayPal Provisioning Platform?

Yes. Existing partner integrations can continue to use the same client id. Work with your PayPal Integration team to get the same client id provisioned.

Will existing linked cards on the legacy platform need to be re-linked on PayPal Provisioning Platform?

Yes. Existing users need to consent to additional permissions so they must go through the new consent flow. PayPal will regenerate a new authorization code to be exchanged for a new Refresh token.

What additional security does PayPal Provisioning Platform provide?

For optional additional security, you can send the credit card PAN in encrypted format.

PayPal supports these algorithms:

RSA1_5
RSA_OAEP
RSA_OAEP_256

For content encryption, which is key-generated by the partner, PayPal supports these algorithms:

A128CBC_HS256
A192CBC_HS384
A256CBC_HS512
A128GCM
A256GCM
A192GCM
A128CBC_HS256_DEPRECATED
A128CBC_HS256_DEPRECATED

For more information, see Encryption.

What is the process to get the PAN encryption public key?

Your PayPal Integration team will generate the public key and send it securely to you when you provide your Sandbox and Production client id to the team.

Why do I need two different APIs for PayPal Provisioning Platform?

Using a separate Linked Instrument API in the partner-initiated flow makes building out the PayPal-initiated flow much simpler.

Does the user need to have the PayPal app installed on the device in order to add a card?

No. The PayPal user does not need to have the PayPal app installed on their device. If the PayPal app is not installed, the user can still go through the PayPal mobile web experience to login and add a card. If the PayPal user has the PayPal app installed, the experience will be more seamless and faster.

Can I link the same card again? Does PayPal reject a duplicate card?

PayPal accepts the same card again and does not create duplicate cards. It silently accepts the card and handles it elegantly without any errors.

Does the user address sent in the Consumer Referral API have to match the address data in the PayPal system? Will PayPal reject card linking and send an error if the addresses do not match?

No. The user address does not have to match and PayPal does not validate by comparing the address provided. If the address is different, we make another address entry and notify the user. PayPal will also send out an email notification if a new address is added. Currently, PayPal only accepts five-digit zip codes. Nine-digit zip codes are interpreted as new addresses.

Can the user change the PayPal email address during the onboarding flow?

Yes. The PayPal user can change their email address during the onboarding flow to an address that could be different from what was provided in the Consumer Referral API call. PayPal will send the matching customer id in the webhook payload which can be queried using the userinfo resource of the Identity API call. For more information, see userinfo.

Can the same card be added to multiple PayPal accounts?

Yes. The same authorized card can be added to multiple PayPal accounts. For example, family members can share the same card.

How many cards can be linked in one PayPal account?

24 cards can be added to a verified PayPal account. 12 cards can be added to an unverified PayPal account. Verified means the user has received and responded to an email that checks on whether the email they provided actually belongs to them.

Can there be multiple return URLs? How can a user return to a specific return URL?

Yes. You can set up multiple URLS using the PayPal Developer Portal. You can send one of the URLs listed in the Developer Portal as a query parameter in the redirect call after the Consumer Referral API call. By default, PayPal sends the user to the first return URL listed in the Developer Portal. For more information, see Redirect User to PayPal

Can I add a mobile deep link as return URL?

Yes. You can add a mobile deep link, for example, paypal://to.my.returnurl. However, currently you cannot add a deep link like this from the PayPal Developer Portal. Contact the PayPal Integration team to have it configured for you.

How do I know if the onboarding was successful?

If the user data was accepted and the user consented to the permissions requested in the consent flow, PayPal returns the authorization code as a query parameter to the configured partner return URL. If the onboarding was not successful, the error codes listed here Return URL Errors are returned.

Does the PayPal user have to log in to PayPal every time a card is linked to PayPal?

No. Once the user has consented and the partner has stored the Refresh Token, the Refresh Token can be used for subsequent linking. For more information, see Add More Cards.

How does the partner know if a failure caused the card to not be linked?

PayPal sends Webhook notifications to the partner's registered Webhook listener endpoint for both card success and failure scenarios. For more information, see Enable Webhook Events.

What do I need to start testing APIs?

In order to submit testing calls to the Sandbox, you need to get your client id provisioned. This process can take some time so we recommend that your first step should be to contact the PayPal Integration team about provisioning your client id.

Before you begin testing, review the P3 documentation at PayPal Provisioning Platform and the REST API general documentation to learn how to:

Set up your development environment in the Developer Portal.

Create a business account using a corporate Distribution List (DL) email address.

Create a REST app, ensuring you add a temporary return URL which you can change later.

Create test accounts.

What fields are required in the Consumer Referral API call?

You need the following fields for the Consumer Referral API call:

person_details/locale

paypal_account_properties/account_country_code

For example:

1{
2    "person_details":{
3        "locale":"en_US"
4    },
5    "paypal_account_properties":{
6        "account_country_code":"US"
7    }
8}

For more information, see Consumer referrals post request body.

What fields are required in the Linked Instrument API call?

You need the following fields for the Linked Instrument API call:

identifier

reference_financial_instrument_id

expiry_date

account_holder_name

For more information, see Linked instruments request