Delay disbursement
DocsCurrent
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 Onboard Sellers before you begin this integration. You must onboard your seller with the DELAY_FUNDS_DISBURSEMENT feature to use 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
intenttocapturein 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-m.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-m.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
intentfield to determine when you want to capture funds. In this example,intentis set toCAPTUREto immediately capture the funds. - Use the
purchase_units/payeeobject to specify the end receiver of the funds. - Set the
purchase_units/payment_instruction/disbursement_modefield toDELAYED. - Use the
purchase_units/payment_instruction/platform_feesarray to specify fees for the order. You must onboard your seller with the PARTNER_FEE feature to use this array.
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-m.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-m.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 toAPPROVEDwhen 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-m.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-m.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-m.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-m.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-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"
}'
Funds are automatically disbursed to the seller after 28 days.
Note: PayPal deducts fees from the seller’s funds.