Pay Out a Delayed Disbursement

PayPal for Partners is a closed loop of networks held together by mutual trust. As the partner and/or platform operator, you have the responsibility to ensure the best customer experience for both customers and sellers. Holds provide a unique way of managing trust and safety because they allow you to hold and disburse funds on terms you set on a transaction-by-transaction basis.

How it works

  • Decide, on a transaction basis, if you’d like to delay the movement of funds between your customers and sellers. This could give you time to conduct additional vetting or enforce other platform-specific business logic.

  • Specify that you want to delay the disbursement of funds.

  • Ensure you have permission from your seller for DELAY_FUNDS_DISBURSEMENT in the rest_endpoint_feature object.

  • When conditions to release funds are met, disburse the funds.

Integration steps

  1. Before you can integrate a PayPal product or solution, you must set up your development environment to get OAuth 2.0 client ID and secret credentials for the sandbox and live environments. You exchange these credentials for an access token that authorizes your REST API calls. To test your web and mobile apps, you create sandbox accounts.

    See Get Started.
  2. Create an order.
  3. Capture an order.
  4. Disburse funds.

Create an order

In the POST v2/checkout/orders/ call, include the Authorization, Accept, PayPal-Request-Id, and Content-Type headers.

Set these parameters to create an order:

Parameter Type Required Description

intent

string

Required

The intent to either capture payment immediately or authorize a payment for an order after order creation. The allowed values are:

  • CAPTURE. The merchant intends to capture payment immediately after the customer makes a payment.
  • AUTHORIZE. The merchant intends to authorize a payment and place funds on hold after the customer makes a payment. Authorized payments are guaranteed for up to three days but are available to capture for up to 29 days. After the three-day honor period, the original authorized payment expires and you must re-authorize the payment. You must make a separate request to capture payments on demand.

payer

object

Optional

The customer who approves and pays for the order. The customer is also known as the payer.

purchase_units

array (contains the purchase_unit_request object)

Required

An array of purchase units. At present only 1 purchase_unit is supported. Each purchase unit establishes a contract between a payer and the payee. Each purchase unit represents either a full or partial order that the payer intends to purchase from the payee.

Within this array is the payment_instruction object. You must set the disbursement_mode field to DELAYED to have funds held for a finite number of days.

application_context

object

Optional

Customize the payer experience during the approval process for the payment with PayPal.

When you create an order, its status is created. You pass the order ID that the create order call returns in subsequent calls.

Request

Example create order request:

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: EXAMPLE_MP" \
  -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"
        },
        "payee": {
          "email_address": "seller@example.com"
        }
      }]
    }
  }]
}'

Response

A successful request returns the HTTP 201 Created status code and a JSON response body that includes the PayPal-generated order ID.

{
  "id": "5O190127TN364715T",
  "status": "CREATED",
  "links": [
    {
      "href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/checkoutnow?token=5O190127TN364715T",
      "rel": "approve",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T/capture",
      "rel": "capture",
      "method": "POST"
    }
  ]
}

Capture an order

After a payment has been created, capture the order to to transfer funds from the buyer's account to the managed account with POST /v2/checkout/orders/{order_id}/capture.

Include the Content-Type, PayPal-Request-Id, and Authorization headers and pass the order ID as a path parameter to /v2/checkout/orders/{order_id}/capture.

Sample API request

curl -v -X POST https://api.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/capture \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: 7b92603e-77ed-4896-8e78-5dea2050476a"

Sample API response

A successful request returns the HTTP 201 Created status code and a JSON response body that includes an id.

{
  "id": "5O190127TN364715T",
    "status": "CREATED",
    "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"
      }
    ]
  }

Disburse funds

To make a payment disbursement, pass the following request parameters to to v1/payments/referenced-payouts-items:

Parameter Description
reference_id The transaction ID for the payout. The pay for order call generates a webhook that returns the transaction ID.
reference_type The reference type. Set to TRANSACTION_ID.

Sample request

curl -v https://api.sandbox.paypal.com/v1/payments/referenced-payouts-items \
  -X POST \
  -H "Content-Type: application/json" \
  -H "PayPal-Request-Id: 7b92603e-77ed-4896-8e78-5dea2050476a" \
  -H "Authorization: Bearer Access-Token" \
  -H "PayPal-Partner-Attribution-Id: Example_Marketplace" \
  -d '{
  "reference_id": "29N36144XH0198422",
  "reference_type": "TRANSACTION_ID"
}'

Sample response

A successful request returns the HTTP 200 Success status code and a JSON body that includes a status message of SUCCESS along with a reference_id for the payment.

{
  "item_id": "g8rfiM0u38L_FJ6qqA-3yHjaTFuTEjdK5ef2WbcpdDsQOci_Lk-we3dHjNNpEcY=",
  "processing_state": {
    "status": "SUCCESS"
  },
  "reference_id": "29N36144XH0198422",
  "reference_type": "TRANSACTION_ID",
  "payout_transaction_id": "67B93249N8969944D",
  "external_reference_id": "7b92603e-77ed-4896-8e78-5dea2050476a",
  "payout_amount": {
    "currency_code": "USD",
    "value": "0.27"
  },
  "payout_destination": "B2A2BDS5DBA4Y",
  "links": [
  {
    "href": "https://api.sandbox.paypal.com/v1/payments/referenced-payouts-items/g8rfiM0u38L_FJ6qqA-3yHjaTFuTEjdK5ef2WbcpdDsQOci_Lk-we3dHjNNpEcY=",
    "rel": "self",
    "method": "GET",
    "encType": "application/json"
  }]
}

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

Feedback