Onboard sellers after payment

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

Know before you code

To use this integration, you must:

• Be an approved partner.
• Have an access token.
• Notify your sellers that you are enabling PayPal as a payment option 30 days in advance and let them opt out. If a seller opts out, let them cancel any pending PayPal transactions.
• Inform your sellers of PayPal's Seller Protection policy, which provides examples of scenarios in which the protection doesn't apply. For example, the seller is not protected if they ship to a different address than the one listed in the transaction confirmation.

• Use Postman to explore and test PayPal APIs.

Seller eligibility

Onboarding sellers after payment supports:

• Sellers with PayPal business accounts.
• Sale payments that are captured immediately.

Onboarding sellers after payment doesn't support:

• Alternative payment methods
• Authorization payments that are placed on hold on the customer’s card.

1. Review onboarding checklist

Before you integrate, work with your account manager to determine the types of PayPal accounts and payment options available to your sellers. For more information, see the onboarding checklist.

2. Make payment

Follow the steps on the Set up payments page to make a payment from a buyer to a seller. 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.

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: Capture order returns an HTTP 422 error when Onboard After Payment is toggled off, and the email_address field of the payee object isn't associated with a PayPal account connected to your platform. Make sure you enable the Onboard After Payment setting in your REST app settings. For more information, see HTTP status codes.

3. Seller signup

Sellers are notified by email that funds are 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.

Note: Several countries have additional regulations related to receiving payment. 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 seller:

• Creates a PayPal account.
• Grants you permission to perform payment.
• Confirms the email address of the account.

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.

You can receive a notification when your seller completes onboarding by subscribing to the MERCHANT.ONBOARDING.COMPLETED webhook. This webhook is triggered when the seller has fulfilled all onboarding requirements.

Next steps

Set up payments.