Progressive Onboarding

Important: PayPal for Marketplaces is available to select partners for approved use cases. For more information, reach out to your PayPal account manager or contact us.

Overview

Progressive onboarding is a form of Connected onboarding that easily allows buyers to pay with PayPal across all of your merchants, even for merchants who don't yet have PayPal accounts. Merchants complete PayPal signup later in order to access their funds. The process begins with a customer making a PayPal purchase from a merchant. As the partner, you send the transaction to PayPal, and PayPal does the rest.

Note: Progressive onboarding is one way in which to onboard your merchants. We also offer an Upfront onboarding experience.

Prerequisites

Before you can use the Connected Onboarding API:

Integration steps

1. Required Inform your merchants that PayPal is enabled.
2. Required Make an Order API call with the merchant's email address where payments will be received.
3. Required Tell merchants to complete setup.

Note: Partners should allow merchants who choose not to use PayPal to cancel received pending payments by using the Cancel API.

Inform your merchants

Merchants can take payments automatically. For existing merchants on your platform, you must:

  • Notify them 30 days prior to activating PayPal.
  • Allow them to opt out.

For new merchants, you must get consent for PayPal to be a default payment option.

Make an Order API call

Using the email address where payments will be received, merchants can make an order call. With progressive onboarding, merchants do not need a PayPal account to start receiving payments. Once they receive a payment merchants are notified to complete onboarding to get access to the funds.

Just make an order API call by passing the merchant’s email address as the “payee” in the request body.

Before making the payment call, as a best practice you should confirm the email address where the merchant would like to receive PayPal payments.

Note: Once a payment is made to a specific email address, the merchant has to complete onboarding with the same email address within 30 days of receiving the payment. Otherwise the payment will be reversed. If the merchant wishes to change the email address they still need to complete onboarding using the email address where payments were received. Once that is completed they can create a new account or use a different email for payments which they will receive in the future.

Complete setup

Tell your merchants to complete setup once they receive a pending transaction due to the seller_setup_pending message. Once merchants receive this pending transaction, they are notified by PayPal to complete onboarding within 30 days.

PayPal also sends several reminders to merchants to complete setup. Existing PayPal account holders who have not completed linking their PayPal account with the Partner (by granting third party permissions) would also be reminded once they log in to claim the funds by completing setup.

Note: Several countries may have additional regulations related to receiving payments. Tell the merchant to check their accounts after logging in for any pending tasks.

Cancel API

If merchants decide they don't want to finish setting up a PayPal account, you must provide them with the option to cancel pending PayPal transactions. When a merchant cancels any pending transaction, all pending transactions are canceled. Call this API endpoint and pass the merchant_email parameter in the request body:

/v1/customer/cancel-onboarding

Here's a sample:

\* Sandbox */
https://api.sandbox.paypal.com/v1/customer/cancel-onboarding 
\* Production */
https://api.paypal.com/v1/customer/cancel-onboarding
curl -v https://api.sandbox.paypal.com/v1/customer/cancel-onboarding 
  -H Content-Type:application/json 
  -H 'Authorization:Bearer A101.F8Lc3Ja_qOA-62-PnPkJ_QqoDdb3AQspzqp0fS88odZ9BJg64od6Vn3Na5-dhEQ3.hDT5IfmvAImZEKbz5EuETWz2m0u' 
  -d '{
  "merchant_email ": "johndoe@example.com"
}'

This call returns one of the following HTTP status codes:

  • 204 No Content Success. The call successfully canceled all transactions for the merchant associated with the specified email address.
  • 400 Validation Error. One or more fields contain erroneous data. See REST API errors.
  • 401 Unauthorized Request. Invalid access token. See REST API errors.
  • 402 Failed Request. Temporary connectivity or server stability issues. Retry, and if the error continues, contact PayPal for further diagnosis and resolution.
  • 403 Forbidden. You don't have appropriate access to use this resource. Contact PayPal for further diagnosis and resolution.
  • 404 Resource Not Found. Configuration issue with PayPal. Contact PayPal for further diagnosis and resolution.
  • 50X PayPal Server Error. Configuration or server issue with PayPal. Contact PayPal for further diagnosis and resolution.

Webhooks

Note: Webhooks will be sent only after the merchant has completed all steps to receive payments described above in prerequisites and integration steps. Each country may have the merchant complete a series of tasks in order to complete the setup process. If any of the steps are missing, the webhook will not be sent.

When you send a transaction to PayPal for a merchant who has not completed their account setup, the status of the transaction is set to pending. PayPal sends a PAYMENT.CAPTURE.PENDING webhook with the reason code seller_setup_pending.

Once the merchant has completed PayPal account setup, PayPal sends these webhooks:

  • PAYMENT.CAPTURE.COMPLETED to indicate that the payment capture has changed from pending to completed.
  • MERCHANT.ONBOARDING.COMPLETED to indicate that the merchant has completed account setup. You can subscribe to webhooks to be alerted when a merchant's account setup is complete.

PayPal also sends the MERCHANT.PARTNER-CONSENT.REVOKED webhook when the merchant account is closed, or the account setup consents have been revoked.

For more information about these webhook events, see Webhook event names.

Congratulations

You have completed Connected path onboarding.

Next: To add PayPal to your checkout experience, see the Orders Integration Guide.