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.

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

Integration steps

  1. Get an access token
  2. Create an order
  3. Capture an order
  4. Disburse funds

Get an access token

To get an access token, pass your OAuth credentials in a get access token call.

Request sample

curl -v https://api.sandbox.paypal.com/v1/oauth2/token \
  -H "Accept: application/json" \
  -H "Accept-Language: en_US" \
  -u "client_id:secret" \
  -d "grant_type=client_credentials"

Response sample

In response, the PayPal authorization server issues an access token.

{
  "scope": "https://uri.paypal.com/services/subscriptions https://api.paypal.com/v1/payments/.* https://api.paypal.com/v1/vault/credit-card https://uri.paypal.com/services/applications/webhooks openid https://uri.paypal.com/payments/payouts https://api.paypal.com/v1/vault/credit-card/.*",
  "nonce": "2017-06-08T18:30:28ZCl54Q_OlDqP6-4D03sDT8wRiHjKrYlb5EH7Di0gRrds",
  "access_token": "Access-Token",
  "token_type": "Bearer",
  "app_id": "APP-80W284485P519543T",
  "expires_in": 32398
}

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.

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