Connected Path Progressive Onboarding

DOCS

Last updated: Feb 27th, 8:33am

Overview

With progressive onboarding, your sellers Log in with PayPal after they accept PayPal payments from buyers on your platform.

Note: Progressive onboarding only supports onboarding sellers with PayPal business accounts. Progressive onboarding does not support:

Casual sellers.

Sellers accepting alternative payment methods.

Delayed disbursements.

How it works

A buyer makes a purchase from a seller on your platform using PayPal. Your seller will be notified by PayPal to sign up for a PayPal account and connect to your platform in order to claim their money.

Important: If your seller receives a PayPal payment but has not completed onboarding, the payment is considered pending. You can use the refund API to refund money for pending payments. If your seller does not sign up after thirty days from the first transaction, all transactions are automatically canceled.

Integration steps

Before integrating progressive onboarding, you must complete Partner Onboarding, and you must be an approved partner. Then, complete the following steps:

Make a payment.

Seller signs up on PayPal.

Track seller onboarding status.

1. Make a payment

Follow the steps on the Add Smart Payment Buttons page to make a payment from a buyer to a seller. In the step to create an order, pass the email address of the seller that you want to onboard as the value for the email_address field in the payee object:

Request

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders
2     -H 'Content-Type: application/json' 
3    -H 'Authorization: Bearer <Access-Token>'
4    -H 'PayPal-Partner-Attribution-Id: <BN-Code>'
5    -d '{
6        "intent": "CAPTURE",
7        "purchase_units": [{
8             "amount": {
9                 "currency_code": "USD",
10                "value": "100.00"
11            },
12            "payee": {
13                "email_address": "seller@example.com"
14            },
15            "payment_instruction": {
16                "disbursement_mode": "INSTANT",
17                "platform_fees": [{
18                     "amount": {
19                         "currency_code": "USD",
20                         "value": "25.00"
21                        }
22                    }]
23                }
24            }]
25        }'

Important: If you are not interested in this feature, work with your account manager to turn it off. If this feature is off, capture order returns a 422 when the value of the email_address field of the payee object is not associated with a PayPal account connected to your platform.

2. Seller signs up on PayPal

After a seller receives payment, they are notified to either sign up for a PayPal account or log in to an existing one. They are then asked to grant you permissions to act on their account on their behalf. If the seller wants to use a different email address, they still need to sign up using the email address they were notified with. They can later create a new account or use a different email for future payments.

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

3. Track seller onboarding status

Seller onboarding is complete when the following requirements are met:

Seller creates a PayPal account.

Seller grants you permission to perform payment.

Seller confirms the email address of the account.

Upon being notified of payment, the seller will have 30 days to complete onboarding. If the seller does not complete onboarding within 30 days, the payment will be reversed to the buyer. To receive a notification for when your seller completes onboarding, you can subscribe to the MERCHANT.ONBOARDING.COMPLETED webhook. This webhook is triggered when the seller has fulfilled all three onboarding requirements.