partners

Delayed Disbursements

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 buyers 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.

Connected Path

Here’s how it works:

  • Decide whether to delay the disbursement of funds between you and your sellers and set those specifications. For example, you might want a certain set of rules for new users to your platform and another set of rules for long-time sellers.

  • When the conditions you specify are met, disburse the funds. PayPal completes a final round of risk and compliance checks before settling funds to the seller.

With flexible holds and disbursements, you have the opportunity to manage your reputation on your platform, while PayPal’s overall risk management protects you from loss liability.

Managed Path

Here’s how it works:

  • Decide, on a transaction basis, if you’d like to delay the movement of funds between you and your 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. Pay an order
  3. 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
}

Pay an order

In addition to the standard Accept, Content-Type, PayPal-Request-Id, and Authorization headers, include the PayPal-Client-Metadata-Id and PayPal-Partner-Attribution-Id headers.

In the URL, specify the order ID returned in the create order call.

In the JSON request body, set the disbursement_mode parameter to DELAYED. PayPal holds the money until you call /v1/payments/referenced-payouts-items/ to disburse funds.

Request sample

This sample shows a single-seller cart with a delayed payout.

curl -v https://api.sandbox.paypal.com/v1/checkout/orders/5O190127TN364715T/pay \
  -X POST \
  -H "PayPal-Client-Metadata-Id: 1495725899514oren" \
  -H "PayPal-Request-Id: 9c5e3668-cb92-4a40-99b7-c74cb68913f4" \
  -H "PayPal-Partner-Attribution-Id: Example_Marketplace" \
  -H "Authorization: Bearer <var>Access-Token</var>" \
  -H "Content-Type: application/json" \
  -d ‘{
  "disbursement_mode": "DELAYED"
}’

Response sample

A successful request returns the HTTP 202 Accepted status code and a JSON response body that shows order and payment details.

{
  "order_id": "5O190127TN364715T",
  "status": "APPROVED",
  "payer_info": {
    "email": "test_payer@example.com",
    "first_name": "Jake",
    "last_name": "Doe",
    "payer_id": "9WVBNYPKKNBJS",
    "phone": "4087811648",
    "country_code": "US",
    "shipping_address": {
      "recipient_name": "John Doe",
      "default_address": false,
      "preferred_address": false,
      "primary_address": false,
      "disable_for_transaction": false,
      "line1": "2211 N First Street",
      "line2": "Building 17",
      "city": "San Jose",
      "country_code": "US",
      "postal_code": "95131",
      "state": "CA"
    }
  },
  "create_time": "2017-04-26T21:21:50Z",
  "update_time": "2017-04-26T21:21:50Z",
  "links": [
  {
    "href": "https://api.paypal.com/v1/checkout/orders/8RU61172JS455403V",
    "rel": "self",
    "method": "GET"
  }]
}

Disburse funds

To make a payment disbursement, pass both the reference_id, the transaction ID returned on a webhook from the pay an order call, and the reference_type as TRANSACTION_ID in the request body.

Request sample

curl -v https://api.sandbox.paypal.com/v1/payments/referenced-payouts-items \
  -X POST \
  -H "Content-Type: application/json" \
  -H "PayPal-Request-Id: 9c5e3668-cb92-4a40-99b7-c74cb68913f4" \
  -H "Authorization: Bearer <var>Access-Token</var>" \
  -H "PayPal-Partner-Attribution-Id: Example_Marketplace" \
  -d '{
  "reference_id": "29N36144XH0198422",
  "reference_type": "TRANSACTION_ID"
}'

Response sample

A successful request returns the HTTP 200 Success status code and includes the following response body.

{
  "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": "postman-request-1480713480",
  "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"
  }]
}
Feedback