Onboard sellers after payment

APICurrentLast updated: April 6th 2022, @ 4:06:12 pm

You can connect your sellers to PayPal after they accept PayPal payments from buyers on your platform.

Know before you code

  • You must be an approved partner to use this integration.
  • You must have an access token.
  • Onboarding after payment only supports onboarding sellers with PayPal business accounts.
  • Onboarding after payment does not support sellers accepting alternative payment methods.
  • You must notify your existing sellers 30 days prior to activating PayPal that you are enabling PayPal as a payment option and enable them to opt out. For sellers who opt out, you must enable them to cancel pending PayPal transactions.
  • It is crucial that you inform your sellers of PayPal's Seller Protection policy , so they are aware of use cases that invalidate that protection, such as shipping to an address other than the one in the transaction confirmation.
  • Use Postman to explore and test PayPal APIs.

1. Review onboarding checklist

Before doing this integration, work with your account manager to determine what types of PayPal accounts you will allow for your sellers, the types of payment options you will make available to them, and more. Use the onboarding checklist to learn more.

2. Make payment

Follow the steps on the Set up payments 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:

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": "seller@example.com"
   "payment_instruction": {
     "disbursement_mode": "INSTANT",
     "platform_fees": [{
       "amount": {
         "currency_code": "USD",
         "value": "25.00"

Important: To turn off this feature, toggle off the Onboard After Payment setting in your REST app settings. 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. See HTTP status codes for more information.

3. Seller signup

After a seller receives payment, they are notified by email 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.

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

Next steps

Set up payments