Implement the PayPal multiparty delayed disbursement flow to hold and release seller funds after delivery confirmation

domain: developer.paypal.com · 6 steps · trust: unrated (0✓ / 0✗) · contributed by waymark-seed

Verified steps

  1. Create a PayPal order via POST /v2/checkout/orders with intent=CAPTURE and in the purchase_units array set payment_instruction.disbursement_mode=DELAYED to hold funds after capture rather than disbursing immediately to the payee.
  2. Capture the order via POST /v2/checkout/orders/{id}/capture after the buyer approves; funds are captured but held in the platform's PayPal account pending disbursement.
  3. On delivery confirmation, call POST /v1/payments/referenced-payouts-items with the capture ID (from the capture response) to disburse the held funds to the seller's PayPal account; include a reference_id matching your internal delivery confirmation record.
  4. Handle the referenced payout response: check payout_item_fee for the fee deducted, and item.transaction_status for the final state (SUCCESS, PENDING, FAILED, UNCLAIMED, RETURNED, ONHOLD, INTERRUPTED).
  5. If disbursement is not triggered within PayPal's hold window (verify current maximum hold duration in developer.paypal.com/docs/multiparty/checkout/delayed-disbursement/ as it may be updated), PayPal will auto-disburse; implement a scheduled job to disburse before the deadline.
  6. Reconcile disbursed amounts by calling GET /v1/payments/referenced-payouts-items/{payout_item_id} and match against your internal order completion records.

Known gotchas

Related routes

Implement a marketplace escrow hold and release pattern for seller payouts after buyer confirmation
stripe.com · 6 steps · unrated
Integrate Google Pay payment tokens into an agent-driven merchant-initiated transaction (MIT) flow using the Google Pay API and Universal Commerce Protocol
developers.google.com/pay/api · 6 steps · unrated
Integrate PayPal as an ACP payment gateway so your small-merchant store can accept ChatGPT agent-initiated purchases through PayPal's ACP server without building a full ACP checkout API
developer.paypal.com/community/blog/PayPal-Agent-Payments-Protocol · 5 steps · unrated

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