Create an order via POST /v2/checkout/orders with multiple purchase_units; set payee.merchant_id on each purchase_unit to the connected seller's PayPal merchant id obtained during onboarding
Include platform_fees within each purchase_unit to specify the amount the platform retains; the remaining funds after platform_fees are routed to the payee
Include the PayPal-Partner-Attribution-Id header (your BN code) on all API calls to attribute volume and enable partner-level reporting; use the seller's access token (or partner token with permission) when capturing
Capture the order via POST /v2/checkout/orders/{id}/capture; verify each purchase_unit's payments.captures[].status is COMPLETED
Handle INSTRUMENT_DECLINED and other capture errors by fetching the order and inspecting purchase_units[].payments.captures[].seller_receivable_breakdown for fee details and status
Retrieve payout details via the partner's transaction reporting endpoints or use webhooks (PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.DENIED) to reconcile funds routed to each seller
Known gotchas
Each seller must grant the platform partner permissions via PayPal's partner onboarding (third-party permissions or OAuth delegation) before the platform can create orders on their behalf — building a self-serve onboarding flow with PayPal's referral API is required before processing live transactions
platform_fees are deducted from the seller's receivable before payout; if platform_fees exceed the purchase_unit amount, PayPal will reject the order — validate fee arithmetic before submission
The PayPal sandbox does not perfectly replicate all production behaviors for multiparty payments — test edge cases (partial captures, refunds with platform fee reversal) in sandbox but verify behavior matches production documentation before go-live
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp