Onboard sellers after payment

API Current

Last updated: Dec 2nd, 7:44am

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.
Get access token

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.
See Partner Referrals API

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

  • 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:

  1. Select Apps & Credentials.
  2. Select the name of your REST app.
  3. Go to Sandbox Webhooks > Add Webhook.
  4. Enter the URL for your listener.
  5. 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.

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:

  • 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}'
    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.

    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:

    • 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.
    ReferencePayPal.comPrivacyCookiesSupportLegalContact

    If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more