Delay disbursement

You can hold funds captured from a payer before disbursing to your merchant. Holding funds gives you time to conduct additional vetting or enforce other platform-specific business logic.

Know before you code

• Complete merchant onboarding.
• Integrate Checkout.

1. Create an order

Create an order to capture funds, and:

• Use the intent field to determine when you want to capture funds. In this example, intent is set to CAPTURE to immediately capture the funds. You can also set intent to AUTHORIZE to authorize your buyers' funds before you capture them.
• Use the purchase_units/payee object to specify the end receiver of the funds.
• Set the purchase_units/payment_instruction/disbursement_mode field to DELAYED.
• Use the purchase_units/payment_instruction/platform_fees array to specify fees for the order.

Sample request

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders
2 -H 'Content-Type: application/json'
3 -H 'Authorization: Bearer ACCESS-TOKEN'
4 -H 'PayPal-Partner-Attribution-Id: BN-CODE'
5 -d '{
6 "intent": "CAPTURE",
7 "purchase_units": [{
8   "amount": {
9     "currency_code": "USD",
10     "value": "100.00"
11   },
12   "payee": {
13     "email_address": "merchant@example.com"
14   },
15   "payment_instruction": {
16     "disbursement_mode": "DELAYED",
17     "platform_fees": [{
18       "amount": {
19         "currency_code": "USD",
20         "value": "25.00"
21       }
22     }]
23   }
24 }]
25}'

2. Capture an order

After your buyer approves the order, call capture order to capture the buyer's funds:

Sample request

1curl -v -k -X POST https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/capture
2 -H 'PayPal-Partner-Attribution-Id:'BN-CODE;'
3 -H 'Authorization: Bearer ACCESS-TOKEN'
4 -H 'Content-Type: application/json'
5 -d '{}'

Note: Orders can't be captured until the status of the order is set to APPROVED. The order status is set to APPROVED when the buyer successfully completes the checkout flow.

3. Disburse funds

After funds are captured, call /v1/payments/referenced-payouts-items to disburse funds to your seller. Pass a reference_id, which is returned in the response to the show order details call or by reading the purchase_units/payments/captures/id field.

Sample request

1curl -v https://api-m.sandbox.paypal.com/v1/payments/referenced-payouts-items
2  -X POST
3  -H "Content-Type: application/json"
4  -H "Authorization: Bearer ACCESS-TOKEN"
5  -H "PayPal-Partner-Attribution-Id: BN-CODE"
6  -d '{
7  "reference_id": "29N36144XH0198422",
8  "reference_type": "TRANSACTION_ID"
9}'

If you onboard your seller before payment and the seller does not disburse the funds within 28 days, then the funds are automatically disbursed to the seller. If you onboard your seller with managed path, work with your account manager to configure the number of days funds are held before they are automatically disbursed.

Note: PayPal deducts fees from the seller’s funds.