Payouts

Send money immediately to multiple recipients with their emails, phone numbers, or PayPal IDs. PayPal Commerce Platform supports payouts in different currencies than your PayPal balance.

Not a developer? Send payouts from your PayPal business account.

Know before you code

  • Complete the steps in Get started to get the following sandbox account information from the Developer Dashboard:

    • Your personal and business sandbox accounts
    • Your access token
  • Request access to PayPal Payouts.
  • Set up your PayPal business account for Payouts:

    • Confirm your identity
    • Link your bank account
    • Add enough money to cover your payout total, including fees
  • You can send up to 15,000 payments in one API call.
  • This integration uses the Payouts REST API.

How it works

When you initiate a payouts request, the Payouts API:

  1. Validates your request and processes the payouts.
  2. Sends you a status report.
  3. Notifies recipients that they have a payment.

If a recipient has a PayPal or Venmo account, an email or mobile notification will prompt them to log in to their account to get payment details. If they don't have a PayPal or Venmo account, an email or mobile notification will prompt them to open a PayPal or Venmo account to claim their money.

Note: Venmo notifications require a U.S. mobile number and are mobile only.

PayPal recipient notifications

This flow shows the experience for PayPal recipients:

Email without PayPal account

Venmo recipient notifications

This flow shows the experience for Venmo recipients:

Venmo recipient flow

Create a payout

To send a payout, copy the following code and modify it.

Sample request

This sample request creates a payout in USD for three recipients: two PayPal recipients and one Venmo recipient.

API endpoint: Create batch payout

curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/payouts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Access-Token>" \
  -d '{
  "sender_batch_header": {
    "sender_batch_id": "2014021801",
    "recipient_type": "EMAIL",
    "email_subject": "You have money!",
    "email_message": "You received a payment. Thanks for using our service!"
  },
  "items": [
    {
      "amount": {
        "value": "9.87",
        "currency": "USD"
      },
      "sender_item_id": "201403140001",
      "recipient_wallet": "PAYPAL",
      "receiver": "<receiver@example.com>"
    },
    {
      "amount": {
        "value": "112.34",
        "currency": "USD"
      },
      "sender_item_id": "201403140002",
      "recipient_wallet": "PAYPAL",
      "receiver": "<receiver2@example.com>"
    },
    {
      "recipient_type": "PHONE",
      "amount": {
        "value": "5.32",
        "currency": "USD"
      },
      "note": "Thanks for using our service!",
      "sender_item_id": "201403140003",
      "recipient_wallet": "VENMO",
      "receiver": "<408-234-1234>"
    }
  ]
}'

Modify the code

After you copy the code in the sample request, modify the following:

  • Change Access-Token to your access token.
  • Change <receiver@example.com> and <receiver2@example.com> to sandbox account email addresses.
  • Change <408-234-1234> to a sandbox account phone number.
  • Optional: To send payments to Venmo recipients, set recipient_wallet to VENMO. Include a U.S. mobile number and a note in the payout item.
  • Optional: To send a payout in a different currency, set the currency parameter to the payment's currency code. You'll need to make a separate API call for each currency type. PayPal can automatically exchange payments for some currencies, even when you don't hold a balance in that currency.

Note: Payout items default to the recipient_type in the sender_batch_header, unless an item has its own recipient_type. If there's no recipient_type in the sender_batch_header, each item must include its own recipient_type.

Step result

A successful request returns:

  • A return status code of HTTP 201 Created.
  • A JSON response body with the payout_batch_id. Use the payout_batch_id in the show payout batch details endpoint to get a detailed record of each item in the payout.

Tip: You can log into your PayPal business account and see payout details on the Activity and Reports pages.

Sample response

{
  "batch_header": {
    "payout_batch_id": "Y4JB5BNLE8Z88",
    "batch_status": "PENDING",
    "sender_batch_header": {
      "sender_batch_id": "2014021801",
      "recipient_type": "EMAIL",
      "email_subject": "You have money!",
      "email_message": "You received a payment. Thanks for using our service!"
    }
  },
  "links": [{
    "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/Y4JB5BNLE8Z88",
    "rel": "self",
    "method": "GET",
    "encType": "application/json"
  }]
}

Next steps

Test and go live

See also