Single payout

To create a single payout, you make a synchronous payout call that immediately returns the results of the payout.

Deprecation notice:

Synchronous mode will soon be deprecated and is no longer available for new integrations but continues to be supported for existing integrations. A synchronous mode payout immediately returns the results of the payout.

For more information about payouts, see Payouts.

Integration steps

This task flow shows how you might typically use the Payouts REST API:

1. Required Meet the prerequisites.
2. Required Create single payout.
3. Optional Show payout item details.
4. Optional Cancel unclaimed payout.

Prerequisites

Before you can use the Payouts API, you must make your first call and learn about HTTP request headers. If you are a non-US developer, see International Developer Questions.

Create single payout

You make a single payout in synchronous payout mode. To use synchronous mode, specify sync_mode=true in the request URI. In this mode, you can specify only one payout and the payout status appears immediately at the time of payout.

Deprecation notice:

Synchronous mode will soon be deprecated and is no longer available for new integrations but continues to be supported for existing integrations. A synchronous mode payout immediately returns the results of the payout.

This synchronous call makes a single payment of $12.34 to the PayPal user at the shirt-supplier-one@mail.com email address:

curl -v https://api.sandbox.paypal.com/v1/payments/payouts?sync_mode=true \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -d '{
  "sender_batch_header":{
    "sender_batch_id":"2014021801",
    "email_subject":"You have a payout!",
    "recipient_type":"EMAIL"
  },
  "items":[
    {
      "recipient_type":"EMAIL",
      "amount":{
        "value":"1.0",
        "currency":"USD"
      },
      "note":"Thanks for your patronage!",
      "sender_item_id":"201403140001",
      "receiver":"anybody01@gmail.com"
    }
  ]
}'

For information about the URI parameters, see Parameters. For information about request body parameters, see Request.

Because the synchronous request succeeds, the response shows:

{
  "batch_header":{
    "payout_batch_id":"CDZEC5MJ8R5HY",
    "batch_status":"SUCCESS",
    "time_created":"2014-46-14T06:46:22Z",
    "time_completed":"2014-46-14T06:46:23Z",
    "sender_batch_header":{
      "sender_batch_id":"2014021801",
      "email_subject":"You have a payout!"
    },
    "amount":{
      "currency":"USD",
      "value":"1.0"
    },
    "fees":{
      "currency":"USD",
      "value":"0.02"
    }
  },
  "items":[
    {
      "payout_item_id":"VHBFGN95AWV82",
      "transaction_id":"0728664497487461D",
      "transaction_status":"SUCCESS",
      "payout_item_fee":{
        "currency":"USD",
        "value":"0.02"
      },
      "payout_batch_id":"CDZEC5MJ8R5HY",
      "payout_item":{
        "amount":{
          "currency":"USD",
          "value":"1.0"
        },
        "note":"Thanks for your patronage!",
        "receiver":"anybody01@gmail.com",
        "recipient_type":"EMAIL",
        "sender_item_id":"201403140001"
      },
      "time_processed":"2014-46-14T06:46:23Z",
      "links":[
        {
          "href":"https://api.sandbox.paypal.com/v1/payments/payouts-item/VHBFGN95AWV82",
          "rel":"item",
          "method":"GET"
        }
      ]
    }
  ],
  "links":[
    {
      "href":"https://api.sandbox.paypal.com/v1/payments/payouts/CDZEC5MJ8R5HY",
      "rel":"self",
      "method":"GET"
    }
  ]
}

Show payout item details

To show details for an individual payout item, use the payout_item_id for an item from the previous response. You can show item details even if the transaction failed, such as when PayPal declines the payout.

This sample request shows payout item details for the item with ID, 1421342:

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/payouts-item/1421342 \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

To determine the status of a synchronous payout, review the transaction status in the response rather than the batch payout status:

{
  "payout_item_id": "1421342",
  "transaction_id": "4345",
  "transaction_status": "SUCCESS",
  "payout_item_fee": {
    "currency": "USD",
    "value": "0.35"
  },
  "payout_batch_id": "20140724",
  "payout_item": {
    "amount": {
      "value": "9.87",
      "currency": "USD"
    },
    "recipient_type": "EMAIL",
    "note": "Thanks for your patronage!",
    "receiver": "anybody01@gmail.com",
    "sender_item_id": "14Feb_234"
  },
  "time_created": "2014-01-27T10:17:00Z",
  "time_processed": "2014-01-27T10:17:41Z",
  "links": [
    {
      "rel": "self",
      "href": "https://api.sandbox.paypal.com/v1/payments/payouts-item/1421342",
      "method": "GET"
    },
    {
      "rel": "self",
      "href": "https://api.sandbox.paypal.com/v1/payments/payouts-item/1421342/cancel",
      "method": "POST"
    },
    {
      "href": "https://localhost:12380/v1/payments/payouts/NEYJ9G3JNQV78",
      "rel": "batch",
      "method": "GET"
    }
  ]
}

For information about the item transaction status, see transaction_enum under payout_enumerations.

Next, you can optionally cancel an unclaimed payout.

Cancel unclaimed payout

You can cancel an unclaimed transaction. If no one claims the unclaimed item within 30 days, the funds are automatically returned to the sender.

To cancel a payout, specify a payout item ID followed by the /cancel action in the URI. The show batch payout details call shows payout item IDs in payout_item_id fields.

You can cancel only payout items with a transaction_status of UNCLAIMED.

This sample request cancels the payout item with ID, 452345:

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/payouts-item/1421342/cancel \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token"

A successful call returns the payout_item_details object with a RETURNED transaction status:

{
  "payout_item_id": "1421342",
  "transaction_id": "4345",
  "transaction_status": "RETURNED",
  "payout_item_fee": {
    "currency": "USD",
    "value": "0.35"
  },
  "payout_batch_id": "20140724",
  "sender_batch_id": "2014021801",
  "payout_item": {
    "recipient_type": "EMAIL",
    "amount": {
      "value": "9.87",
      "currency": "USD"
    },
    "note": "Thanks for your patronage!",
    "receiver": "anybody01@gmail.com",
    "payouts_item_id": "1421342",
    "sender_item_id": "14Feb_234"
  },
  "time_processed": "2014-01-27T10:17:41Z",
  "errors": {
    "name": "RECEIVER_UNREGISTERED",
    "message": "Receiver is unregistered",
    "information_link": "https://developer.paypal.com/docs/api/payments.payouts-batch#errors"
  },
  "links": [
    {
      "rel": "self",
      "href": "https://api.sandbox.paypal.com/v1/payments/payouts-item/1421342",
      "method": "GET"
    },
    {
      "rel": "batch",
      "href": "https://api.sandbox.paypal.com/v1/payments/payouts/20140724",
      "method": "GET"
    }
  ]
}

For information about the response fields, see Response.

Additional information