Onboard sellers after payment

API Current

Last updated: Mar 19th, 5:40pm

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

Required
To use this integration, you must

Be an approved partner.

Have an access token

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.

Required
This integration uses the Partner Referrals API:

The payment features available to your sellers vary by the type of onboarding you choose. See onboarding options for more information.

Use Postman to explore and test PayPal APIs.

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:

Only the PayPal branded checkout which is the PayPal button.

Immediate capture of payments which are funds that are taken from the buyer immediately with an instant and delayed disbursement.

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

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

Authorization payments which are funds that are placed on hold on the buyer’s card.

PayPal Credit, Venmo, Pay Later, and Alternative payment methods.

Multiseller payments. If you are using multiseller payments, you must create an account before you onboard. Sellers cannot create an account during the onboarding flow when using multiseller payments.

Onboarding after payment doesn’t support:

PayPal personal accounts. All sellers must use a PayPal business account.

Advanced checkout with card field customization.

Saving payment methods.

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:

MERCHANT.ONBOARDING.COMPLETED: This webhook is triggered when the seller has fulfilled all required onboarding and has given you permissions.

MERCHANT.PARTNER-CONSENT.REVOKED: This webhook is triggered when the seller has removed your permissions.

To subscribe to webhooks from the developer portal:

Select Apps & Credentials.

Select the name of your REST app.

Go to Sandbox Webhooks > Add Webhook.

Enter the URL for your listener.

Add the event name by clicking the associated check boxes and select Save.

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

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:

Replace ACCESS-TOKEN with your access token.

Replace BN-CODE with your BN code.

Sample 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 Onboard After Payment isn’t enabled in the REST app settings in the developer portal, and the email_address field of the payee object isn’t associated with a PayPal account connected to your platform, an HTTP 422 error is returned. For more information, see HTTP status codes.

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.

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

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.

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

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:

Tell the seller to complete onboarding, then refund the payment (recommended).

Wait 30 days. The payment will be automatically cancelled after 30 days of pending.

Request the buyer to cancel the payment in their account.

Next steps

Recommended
Standard Checkout

Integrate standard checkout to accept payments.