Delay Disbursement

DocsLast updated: June 15th 2023, @ 5:00:00 pm


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

Integration steps

Before implementing delay disbursement, you must have completed Seller Onboarding and Checkout. Then, complete the following steps:

  1. Create an order.
  2. Capture an order.
  3. Disburse funds.

1. Create an order

Before delaying disbursement, you must first create an order and capture funds. Use the following code to create an order:

  1. cURL
  2. Node
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": "seller@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}'
  • 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. Alternatively, you can 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.

2. Capture an order

Next, after your buyer approves the order, call capture order to capture the buyer's funds.

  1. cURL
  2. Node
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 cannot 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

Once funds are captured, call /v1/payments/referenced-payouts-items to disburse funds to your seller. To make this call you must pass a reference_id. You retrieve the reference_id by making a show order details call and reading the purchase_units/payments/captures/id field.

curl -v https://api-m.sandbox.paypal.com/v1/payments/referenced-payouts-items \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Access-Token>" \
  -H "PayPal-Partner-Attribution-Id: <BN-Code>" \
  -d '{
  "reference_id": "29N36144XH0198422",
  "reference_type": "TRANSACTION_ID"
}'

If you onboard your seller with connected path 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, you can 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.

Next