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.

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.

1. Create 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.

2. Capture 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.

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"
    }
  ]
}

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