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

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.