Delay disbursement

Use this integration to hold funds from a buyer before disbursing it to your seller. Holding funds gives you time to conduct additional vetting. If you want to capture funds immediately, use Immediate capture.

Delayed disbursement supports:

Authorization: Set intent to authorize in the create order call to authorize a payment and place funds on hold after the customer makes a payment.
Capture: Set intent to capture create order call to capture payment immediately after the customer makes a payment.

Note: Funds are automatically disbursed to the seller after 28 days, and PayPal deducts fees from the seller's funds.

Know before you code

To use this integration you must:

Contact us to be an approved partner.
Onboard merchants with the DELAY_FUNDS_DISBURSEMENT feature in the developer dashboard before you use this integration.
Inform your merchants of PayPal's Seller Protection policy, so they are aware of use cases that invalidate that protection, such as shipping to an address other than the one in the transaction confirmation.

Note: This server-side integration uses the Orders REST API for this server-side integration.

1. Generate PayPal-Auth-Assertion header

You'll need to Pass the PayPal-Auth-Assertion header with the standard Content-Type, Authorization, and PayPal-Request-ID headers. In client-side JavaScript, the value of the PayPal-Auth-Assertion header can be generated as follows:

// client-side JavaScript

function encodeObjectToBase64(object) {
  const objectString = JSON.stringify(object);
  return window.btoa(objectString);
}

const clientId = "CLIENT-ID";
const sellerPayerId = "SELLER-PAYER-ID"; // preferred
// const sellerEmail = "SELLER-ACCOUNT-EMAIL"; // use instead of payer-id if required

const header = {
  alg: "none"
};
const encodedHeader = encodeObjectToBase64(header);

const payload = {
  iss: clientId,
  payer_id: sellerPayerId
  // email: sellerEmail
};
const encodedPayload = encodeObjectToBase64(payload);

const jwt = `${encodedHeader}.${encodedPayload}.`; // json web token
console.log(`Paypal-Auth-Assertion=${jwt}`);

Note: The token contains two period (.) characters, which are required according to the JSON web token structure.

Modify the code

Use the client ID of the platform or marketplace from the PayPal Developer dashboard for clientId.
In the given example, the sellerPayerId is the payer ID of the receiving seller's PayPal account. You can also use email instead of payer_id and supply the email address of the seller's PayPal account.

Example functions to generate the PayPal-Auth-Assertion header in other programming environments:

Node.js

// Node.js

function encodeObjectToBase64(object) {
  const objectString = JSON.stringify(object);
  return Buffer
    .from(objectString)
    .toString("base64");
}

const clientId = "CLIENT-ID";
const sellerPayerId = "SELLER-PAYER-ID"; // preferred
// const sellerEmail = "SELLER-ACCOUNT-EMAIL"; // use instead if payer-id unknown

const header = {
  alg: "none"
};
const encodedHeader = encodeObjectToBase64(header);

const payload = {
  iss: clientId,
  payer_id: sellerPayerId
  // email: sellerEmail
};
const encodedPayload = encodeObjectToBase64(payload);

const jwt = `${encodedHeader}.${encodedPayload}.`; // json web token
console.log(`Paypal-Auth-Assertion=${jwt}`);

Java

// Java

import org.apache.commons.codec.binary.Base64;

public class Base64Encode {

  public static void main(String[] args) {
    String clientId = "CLIENT-ID";
    String sellerPayerId = "SELLER-PAYER-ID"; // preferred
    // String sellerEmail = "SELLER-ACCOUNT-EMAIL"; // use instead if payer-id unknown

    String header = "{\"alg\":\"none\"}";
    String payload =
      "{\"iss\":\"" + clientId + "\",\"payer_id\":\"" + sellerPayerId + "\"}";
    // "{"iss":"" + clientId + "","email":"" + sellerEmail + ""}";

    byte[] encodedHeader = Base64.encodeBase64(header.getBytes());
    byte[] encodedPayload = Base64.encodeBase64(payload.getBytes());

    String jwt = new String(encodedHeader) +
      "." +
      new String(encodedPayload) +
      "."; // json web token
    System.out.println("Paypal-Auth-Assertion=" + jwt);
  }
}

2. Create Order

You must first create an order and capture funds. To create an order, copy the following code and modify as follows:

Replace BN-CODE with your PayPal attribution ID.
Replace PAYPAL-AUTH-ASSERTION with your PayPal auth assertion generated from Step 1.
Use the purchase_units/payee object to specify the end receiver of the funds.
Use the purchase_units/payment_instruction/disbursement_mode field to specify when funds should be disbursed to the payee upon calling capture order. In this integration, set this field to DELAYED.
Use the purchase_units/payment_instruction/platform_fees array to specify fees for the order. To use this array, ensure that the merchants are onboarded with the Platform Fee feature enabled for your app. On the app settings page of your app, you can configure specific features. To configure your app to include PARTNER_FEE, from the developer dashboard, navigate to your app settings page and toggle Platform Fee to select the feature.

Sample request - cURL

curl -v -XPOSThttps://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'
-H'PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION'
-d '{
"intent":"CAPTURE",
"purchase_units":[{
"amount":{
"currency_code":"USD",
"value":"100.00"
},
"payee":{
"email_address":"[email protected]"
},
"payment_instruction":{
"disbursement_mode":"DELAYED",
"platform_fees":[{
"amount":{
"currency_code":"USD",
"value":"25.00"
}
}]
}
}]
}'

Sample request - Node

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",
"PayPal-Auth-Assertion":"PAYPAL-AUTH-ASSERTION"
},
body:{
"intent":"CAPTURE",
"purchase_units":[{
"amount":{
"currency_code":"USD",
"value":"100.00"
},
"payee":{
"email_address":"[email protected]"
},
"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
});
});
});

3. Capture Order

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

Copy the following code and modify as follows:

Replace ACCESS-TOKEN with your access token.
Replace BN-CODE with your PayPal partner attribution ID.
Replace PAYPAL-AUTH-ASSERTION with your PayPal auth assertion generated from Step 1.

Sample request - cURL

curl -v -k -X POST https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/capture
-H 'Content-Type: application/json'
-H 'Authorization: Bearer ACCESS-TOKEN'
-H 'PayPal-Partner-Attribution-Id: BN-CODE'
-H 'PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION'
-d '{}'

Sample request - Node

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",
			"PayPal-Auth-Assertion": "PAYPAL-AUTH-ASSERTION"
		}
	}, 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.

4. Show order details

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

Copy the following code and modify as follows:

Replace ACCESS-TOKEN with your access token.
Replace BN-CODE with your PayPal partner attribution ID.
Replace PAYPAL-AUTH-ASSERTION with your PayPal auth assertion generated from Step 1.

Sample request - cURL

curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T
-H "Content-Type: application/json"
-H 'Authorization: Bearer ACCESS-TOKEN'
-H 'PayPal-Partner-Attribution-Id: BN-CODE'
-H 'PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION'

Sample request - Node

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",
		"PayPal-Partner-Attribution-Id": "BN-CODE",
		"PayPal-Auth-Assertion": "PAYPAL-AUTH-ASSERTION"
	}
};
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"
    }
  ]
}

5. 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. Retrieve the reference_id by making a show order details call and note down the urchase_units/payments/captures/id field.

Copy the following code and modify as follows:

Replace ACCESS-TOKEN with your access token.
Replace BN-CODE with your PayPal partner attribution ID.

Sample request - cURL

curl -v https://api-m.sandbox.paypal.com/v1/payments/referenced-payouts-items
-XPOST
-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"
}'

Sample request - Node

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.

Next steps

Integration Checklist

Go through the integration checklist before you go live.

Delayed disbursement supports:

Authorization: Set intent to authorize in the create order call to authorize a payment and place funds on hold after the customer makes a payment.
Capture: Set intent to capture create order call to capture payment immediately after the customer makes a payment.

Note: Funds are automatically disbursed to the seller after 28 days, and PayPal deducts fees from the seller's funds.

Know before you code

To use this integration you must:

Contact us to be an approved partner.
Onboard merchants with the DELAY_FUNDS_DISBURSEMENT feature in the developer dashboard before you use this integration.
Inform your merchants of PayPal's Seller Protection policy, so they are aware of use cases that invalidate that protection, such as shipping to an address other than the one in the transaction confirmation.

Note: This server-side integration uses the Orders REST API for this server-side integration.

1. Generate PayPal-Auth-Assertion header

// client-side JavaScript

function encodeObjectToBase64(object) {
  const objectString = JSON.stringify(object);
  return window.btoa(objectString);
}

const clientId = "CLIENT-ID";
const sellerPayerId = "SELLER-PAYER-ID"; // preferred
// const sellerEmail = "SELLER-ACCOUNT-EMAIL"; // use instead of payer-id if required

const header = {
  alg: "none"
};
const encodedHeader = encodeObjectToBase64(header);

const payload = {
  iss: clientId,
  payer_id: sellerPayerId
  // email: sellerEmail
};
const encodedPayload = encodeObjectToBase64(payload);

const jwt = `${encodedHeader}.${encodedPayload}.`; // json web token
console.log(`Paypal-Auth-Assertion=${jwt}`);

Note: The token contains two period (.) characters, which are required according to the JSON web token structure.

Modify the code

Use the client ID of the platform or marketplace from the PayPal Developer dashboard for clientId.
In the given example, the sellerPayerId is the payer ID of the receiving seller's PayPal account. You can also use email instead of payer_id and supply the email address of the seller's PayPal account.

Example functions to generate the PayPal-Auth-Assertion header in other programming environments:

Node.js

// Node.js

function encodeObjectToBase64(object) {
  const objectString = JSON.stringify(object);
  return Buffer
    .from(objectString)
    .toString("base64");
}

const clientId = "CLIENT-ID";
const sellerPayerId = "SELLER-PAYER-ID"; // preferred
// const sellerEmail = "SELLER-ACCOUNT-EMAIL"; // use instead if payer-id unknown

const header = {
  alg: "none"
};
const encodedHeader = encodeObjectToBase64(header);

const payload = {
  iss: clientId,
  payer_id: sellerPayerId
  // email: sellerEmail
};
const encodedPayload = encodeObjectToBase64(payload);

const jwt = `${encodedHeader}.${encodedPayload}.`; // json web token
console.log(`Paypal-Auth-Assertion=${jwt}`);

Java

// Java

import org.apache.commons.codec.binary.Base64;

public class Base64Encode {

  public static void main(String[] args) {
    String clientId = "CLIENT-ID";
    String sellerPayerId = "SELLER-PAYER-ID"; // preferred
    // String sellerEmail = "SELLER-ACCOUNT-EMAIL"; // use instead if payer-id unknown

    String header = "{\"alg\":\"none\"}";
    String payload =
      "{\"iss\":\"" + clientId + "\",\"payer_id\":\"" + sellerPayerId + "\"}";
    // "{"iss":"" + clientId + "","email":"" + sellerEmail + ""}";

    byte[] encodedHeader = Base64.encodeBase64(header.getBytes());
    byte[] encodedPayload = Base64.encodeBase64(payload.getBytes());

    String jwt = new String(encodedHeader) +
      "." +
      new String(encodedPayload) +
      "."; // json web token
    System.out.println("Paypal-Auth-Assertion=" + jwt);
  }
}

2. Create Order

You must first create an order and capture funds. To create an order, copy the following code and modify as follows:

Replace BN-CODE with your PayPal attribution ID.
Replace PAYPAL-AUTH-ASSERTION with your PayPal auth assertion generated from Step 1.
Use the purchase_units/payee object to specify the end receiver of the funds.
Use the purchase_units/payment_instruction/disbursement_mode field to specify when funds should be disbursed to the payee upon calling capture order. In this integration, set this field to DELAYED.
Use the purchase_units/payment_instruction/platform_fees array to specify fees for the order. To use this array, ensure that the merchants are onboarded with the Platform Fee feature enabled for your app. On the app settings page of your app, you can configure specific features. To configure your app to include PARTNER_FEE, from the developer dashboard, navigate to your app settings page and toggle Platform Fee to select the feature.

Sample request - cURL

curl -v -XPOSThttps://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'
-H'PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION'
-d '{
"intent":"CAPTURE",
"purchase_units":[{
"amount":{
"currency_code":"USD",
"value":"100.00"
},
"payee":{
"email_address":"[email protected]"
},
"payment_instruction":{
"disbursement_mode":"DELAYED",
"platform_fees":[{
"amount":{
"currency_code":"USD",
"value":"25.00"
}
}]
}
}]
}'

Sample request - Node

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",
"PayPal-Auth-Assertion":"PAYPAL-AUTH-ASSERTION"
},
body:{
"intent":"CAPTURE",
"purchase_units":[{
"amount":{
"currency_code":"USD",
"value":"100.00"
},
"payee":{
"email_address":"[email protected]"
},
"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
});
});
});

3. Capture Order

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

Copy the following code and modify as follows:

Replace ACCESS-TOKEN with your access token.
Replace BN-CODE with your PayPal partner attribution ID.
Replace PAYPAL-AUTH-ASSERTION with your PayPal auth assertion generated from Step 1.

Sample request - cURL

curl -v -k -X POST https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/capture
-H 'Content-Type: application/json'
-H 'Authorization: Bearer ACCESS-TOKEN'
-H 'PayPal-Partner-Attribution-Id: BN-CODE'
-H 'PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION'
-d '{}'

Sample request - Node

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",
			"PayPal-Auth-Assertion": "PAYPAL-AUTH-ASSERTION"
		}
	}, 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.

4. Show order details

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

Copy the following code and modify as follows:

Replace ACCESS-TOKEN with your access token.
Replace BN-CODE with your PayPal partner attribution ID.
Replace PAYPAL-AUTH-ASSERTION with your PayPal auth assertion generated from Step 1.

Sample request - cURL

curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T
-H "Content-Type: application/json"
-H 'Authorization: Bearer ACCESS-TOKEN'
-H 'PayPal-Partner-Attribution-Id: BN-CODE'
-H 'PayPal-Auth-Assertion: PAYPAL-AUTH-ASSERTION'

Sample request - Node

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",
		"PayPal-Partner-Attribution-Id": "BN-CODE",
		"PayPal-Auth-Assertion": "PAYPAL-AUTH-ASSERTION"
	}
};
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"
    }
  ]
}

5. Disburse funds

Copy the following code and modify as follows:

Replace ACCESS-TOKEN with your access token.
Replace BN-CODE with your PayPal partner attribution ID.

Sample request - cURL

curl -v https://api-m.sandbox.paypal.com/v1/payments/referenced-payouts-items
-XPOST
-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"
}'

Sample request - Node

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.

Next steps

Integration Checklist

Go through the integration checklist before you go live.

Delay disbursement

On this page

On this page

On this page

We currently use cookies to improve and customize your experience on our site. If you accept, we’ll also use marketing cookies to show you personalized ads. Manage your cookies and learn more.

Delay disbursement

On this page

On this page