Onboard sellers after payment

How it works

You can connect your sellers to PayPal after they accept the first payment from a buyer on your platform.

Know before you code

Seller eligibility

The first payment from the buyer will be pending until the seller goes through the full onboarding flow, which includes confirming their PayPal business account.

If a seller doesn't have a PayPal business account, they must create one during the onboarding flow. PayPal sends an email to the seller which includes a link to go through onboarding, create their account, and grant you permissions. If the seller doesn't create an account before 30 days, the transaction is canceled and the payment is returned to the buyer.

In the first transaction before a seller without a PayPal business account onboards, the following features are available:

In the first transaction before a seller with an existing PayPal business account onboards, the full capabilities of PayPal Checkout are available.

After a seller goes through the onboarding flow, the following features will be available:

Onboarding after payment doesn't support:

1. Set up webhooks

Webhooks are HTTP callbacks that receive notification messages for events. You can subscribe to webhooks from the developer portal or by making an API call.

Subscribe to the following webhooks for onboarding:

To subscribe to webhooks from the developer portal:

You can also subscribe to webhooks by making an API call, see Webhooks for the sample requests and responses.

2. Make Payment

To make a payment from a buyer to a seller, follow the steps on Set up payments. To create an order, pass the email address of the seller you want to onboard in the email_address field of the payee object. Set intent to CAPTURE to capture funds immediately. For more information on your BN code (build notation code), see PayPal-Partner-Attribution-ID.

Modify the code

Copy the sample request and modify it as follows:

Sample request

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer ACCESS-TOKEN' \
 -H 'PayPal-Partner-Attribution-Id: BN-CODE' \
 -d '{
 "intent": "CAPTURE",
 "purchase_units": [{
   "amount": {
     "currency_code": "USD",
     "value": "100.00"
   },
   "payee": {
     "email_address": "[email protected]"
   },
   "payment_instruction": {
     "disbursement_mode": "INSTANT",
     "platform_fees": [{
       "amount": {
         "currency_code": "USD",
         "value": "25.00"
       }
     }]
   }
 }]
}'

3. Send seller signup link

Sellers are notified by email that a payment is pending when they receive payment. The seller must sign up or log in to their PayPal account with the email that the notification was sent. The seller is then asked to grant you permission to act on their account on their behalf. If the seller wants to use a different email address, the seller will still need to sign up for an account with the email address where the notification was sent before creating a new account with a different email.

4. Track seller onboarding status

Seller onboarding is complete when the seller:

After the seller is notified of payment, the seller has 30 days to complete onboarding. If the seller doesn't complete onboarding within 30 days, the payment is returned to the buyer.

The MERCHANT.ONBOARDING.COMPLETED webhook sends a notification when a seller has fulfilled all onboarding requirements.

5. Refund pending transactions

You will not be able to refund a payment on behalf of the seller until they have onboarded. Merchants cannot cancel pending transactions.

The following are options for cancelling pending payments:

Next steps