Delay disbursement

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.

On this page

Know before you code

  • Complete Onboarding before you begin this integration.
  • The instructions in Get started will help you get your access token.
  • This server-side integration uses the Orders REST API.
  • You must set intent to capture in the create order call for this feature to work.
  • In this example, funds are held before disbursing. To capture immediately, use Immediate capture.

Step 1: Create an order

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

curl -v -X POST https://api.sandbox.paypal.com/v2/checkout/orders \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer Access-Token' \
 -H 'PayPal-Partner-Attribution-Id: BN-Code' \
 -d '{
 "intent": "CAPTURE",
 "purchase_units": [{
   "amount": {
     "currency_code": "USD",
     "value": "100.00"
   },
   "payee": {
     "email_address": "seller@example.com"
   },
   "payment_instruction": {
     "disbursement_mode": "DELAYED",
     "platform_fees": [{
       "amount": {
         "currency_code": "USD",
         "value": "25.00"
       }
     }]
   }
 }]
}'
var express = require('express');
var request = require('request');

express()
    .post('/my-server/create-order', function(req, res) {
        request.post('https://api.sandbox.paypal.com/v2/checkout/orders', {
            headers: {
                Content-Type: "application/json",
                Authorization: "Bearer Access-Token",
                PayPal-Partner-Attribution-Id: BN-Code
            },
            body: {
                "intent": "CAPTURE",
                "purchase_units": [{
                    "amount": {
                        "currency_code": "USD",
                        "value": "100.00"
                    },
                    "payee": {
                        "email_address": "seller@example.com"
                    },
                    "payment_instruction": {
                        "disbursement_mode": "DELAYED",
                        "platform_fees": [{
                            "amount": {
                                "currency_code": "USD",
                                "value": "25.00"
                            }
                        }]
                    }
                }],
            },
            json: true
        }, function(err, response, body) {
            if (err) {
                console.error(err);
                return res.sendStatus(500);
            }

            res.json({
                id: body.id
            });
        });
    });
  • 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.
  • 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.

Step 2: Capture an order

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

curl -v -k -X POST https://api.paypal.com/v2/checkout/orders/5O190127TN364715T/capture \
 -H 'PayPal-Partner-Attribution-Id: BN-Code' \
 -H 'Authorization: Bearer Access-Token' \
 -H 'Content-Type: application/json' \
 -d '{}'
var express = require('express');
var request = require('request');

express()
     .post('/my-server/handle-approve/:id', function(req, res) {
         var OrderID = req.params.id;
         request.post('https://api.sandbox.paypal.com/v2/checkout/orders/' + OrderID + '/capture', {
             headers: {
                 Content-Type: "application/json",
                 Authorization: "Bearer Access-Token",
                 PayPal-Partner-Attribution-Id: BN-Code
             }
         }, function(err, response, body) {
             if (err) {
                 console.error(err);
                 return res.sendStatus(500);
             }

             res.json({
                 status: 'success'
             });
         });
     });

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.

Step 3: Show order details

To see your order details, pass the order ID as a path parameter in a show order details call.

curl -v -X GET https://api.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
var http = require("https");

var options = {
  "method": "GET",
  "hostname": "api.sandbox.paypal.com",
  "port": null,
  "path": "/v2/checkout/orders/5O190127TN364715T",
  "headers": {
    "content-type": "application/json",
    "authorization: "Bearer Access-Token",
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

A successful request returns the HTTP 200 OK status code and a JSON response body that shows order details.

{
  "id": "5O190127TN364715T",
  "status": "CREATED",
  "intent": "CAPTURE",
  "purchase_units": [
    {
      "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
      "amount": {
        "currency_code": "USD",
        "value": "100.00"
      }
    }
  ],
  "create_time": "2018-04-01T21:18:49Z",
  "links": [
    {
      "href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://www.paypal.com/checkoutnow?token=5O190127TN364715T",
      "rel": "approve",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T/capture",
      "rel": "capture",
      "method": "POST"
    }
  ]
}

Step 4: 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.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 funds are not disbursed within 28 days, they are automatically disbursed to the seller.

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

Next steps

Test and go live