PayPal partner application
Becoming a PayPal partner (Multiparty), the partner REST app, merchant ID and BN code, the partner webhook, seller onboarding and what PayPal must approve.
With PayPal Multiparty a workspace's PayPal Business account ("the seller") gives the platform's REST app permission to create orders, capture, refund and read disputes for it. Each call carries the platform's BN code and names the seller; the payment's payee is the seller. No platform fee is set.
What PayPal must approve first#
Seller onboarding uses the Partner Referrals API, which PayPal opens to approved partners only. Until then every connection attempt is refused by PayPal.
- Create a PayPal Business account for the platform, if there is none.
- At developer.paypal.com, apply to become a partner (PayPal Complete Payments / Multiparty). PayPal asks about the business model; say that sellers are paid directly and the platform takes no fee.
- PayPal enables the Partner Referrals API on your sandbox app first and issues a BN code (partner attribution ID). Production access follows its review.
Add the application#
Super → Platform apps → PayPal:
- Partner app Client ID and Secret — Apps & Credentials → the approved REST app (Sandbox for Test).
- Partner merchant ID — the merchant (payer) ID of the platform's own business account: PayPal → Account settings → Business information.
- BN code — as issued by PayPal.
Save, then Verify. The check obtains a token with the app's keys. PayPal has no call that shows whether the app may use the Partner Referrals API: that is proven when the first workspace connects.
Register the partner webhook#
In the same REST app → Add Webhook:
- Webhook URL — the Platform webhook endpoint shown on the application's page.
- Select the events listed under Events to send:
MERCHANT.ONBOARDING.COMPLETED,MERCHANT.PARTNER-CONSENT.REVOKEDand the payment events. - Copy the Webhook ID into the application.
Events of every seller who granted permission arrive at this one endpoint.
What a workspace does#
Settings → Gateways → Connect PayPal. The owner is sent to PayPal to sign in (or create a Business account) and grant the permissions: payments, refunds, reading disputes and the account's state. Back here, the system asks PayPal which seller completed the sign-up for that set, and for the seller's state:
- Enabled — the seller can receive payments, its e-mail address is confirmed and the permissions are granted.
- Restricted — the seller must confirm the e-mail address of the PayPal account, or PayPal has limited the account.
- Onboarding — the sign-up was not completed.
Ending a connection#
PayPal has no call with which a platform ends a seller's consent. Disconnect ends the connection here; the seller removes the permission in PayPal under Account settings → Website payments → API access. When a seller removes it there first, PayPal reports MERCHANT.PARTNER-CONSENT.REVOKED and the set is revoked.
Go live#
- [ ] PayPal's production approval for the partner app.
- [ ] A Live application with the live Client ID, Secret, merchant ID and BN code.
- [ ] The live webhook with the live application's URL and its Webhook ID.
- [ ] One seller connected, one small real payment and refund.
Common errors#
"PayPal could not start the connection" — the app is not approved for the Partner Referrals API in that environment, or the BN code belongs to another app. The set's page shows PayPal's own message.
The set stays in Onboarding after the owner returned — the owner left PayPal before granting the permissions. Continue at PayPal starts again.
PERMISSION_DENIED on a payment — the seller removed the permission. Press Check status now; the set becomes Revoked.