Onboard sellers after payment
APICurrentLast updated: April 6th 2022, @ 4:06:12 pm
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 thepayee
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.