partners

Instant Payouts

You can payout orders to your sellers instantly using the Orders API.

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 INSTANT. 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 an instant 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": "INSTANT"
}’

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

PayPal disburses the funds to you and to your seller. 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: postman-request-1480716758" \
  -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