Payouts API

Use the Payouts API to make payments to multiple PayPal or Venmo recipients. The Payouts API is a fast, convenient way to send commissions, rebates, rewards, and general disbursements. You can send up to 15,000 payments per call. If you integrated the Payouts API before September 1, 2017, you receive transaction reports through Mass Payments Reporting. Otherwise, view reports from your PayPal Business account. The Payouts API uses the ISO 8601 Internet date and time format.

Payouts (resource group)

Use the /payouts resource to create a batch payout, update the status for a batch payout, show the status of a batch payout with the transaction status and other data for individual payout items, and request approval for a batch payout.

Create batch payout

POST/v1/payments/payouts

Creates a batch payout. In the JSON request body, pass a sender_batch_header and an items array. The sender_batch_header defines how to handle the payout. The items array defines the payout items.
You can make payouts to one or more recipients.

Notes:
PayPal does not process duplicate payouts. If you specify a sender_batch_id that was used in the last 30 days, the API rejects the request with an error message that shows the duplicate sender_batch_id and includes a HATEOAS link to the original payout with the same sender_batch_id.
If you receive an HTTP 5nn status code, you can safely retry the request with the same sender_batch_id.
The Payouts API does not support build notation (BN) codes. In a future Payouts release, you can optionally provide BN codes in the PayPal-Partner-Attribution-Id request header.
For information about the PayPal-Partner-Attribution-Id header, see HTTP request headers. To learn about or request a BN code, contact your partner manager or see PayPal Partner Program.

Header parameters

PayPal-Request-Id
string
The server stores keys for 30 days.

Request body

sender_batch_header
object
required
The sender-provided payout header for a payout request.
items
array (contains the payout_item object)
required
An array of individual payout items.
Minimum length: 1.
Maximum length: 15000.

Sample Request

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": "Payouts_2018_100007",
    "email_subject": "You have a payout!",
    "email_message": "You have received a payout! Thanks for using our service!"
  },
  "items": [
    {
      "recipient_type": "EMAIL",
      "amount": {
        "value": "9.87",
        "currency": "USD"
      },
      "note": "Thanks for your patronage!",
      "sender_item_id": "201403140001",
      "receiver": "receiver@example.com",
      "alternate_notification_method": {
        "phone": {
          "country_code": "91",
          "national_number": "9999988888"
        }
      },
      "notification_language": "fr-FR"
    },
    {
      "recipient_type": "PHONE",
      "amount": {
        "value": "112.34",
        "currency": "USD"
      },
      "note": "Thanks for your support!",
      "sender_item_id": "201403140002",
      "receiver": "91-734-234-1234"
    },
    {
      "recipient_type": "PAYPAL_ID",
      "amount": {
        "value": "5.32",
        "currency": "USD"
      },
      "note": "Thanks for your patronage!",
      "sender_item_id": "201403140003",
      "receiver": "G83JXTJ5EHCQ2"
    }
  ]
}'

Response

A successful request returns the HTTP 201 Created status code and a JSON response body that shows the ID for the payout and payout details. To show payout status, use the payout_batch_id value that appears in the response. If the initial scan that checks for syntax errors, missing or duplicated keywords, and more succeeds, the batch_status is PENDING. The initial scan checks for syntax errors and missing or duplicated keywords. The API does not immediately validate some payout item values, such as the receiver phone numbers.

batch_header
object
The payout header.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "batch_header": {
    "sender_batch_header": {
      "sender_batch_id": "Payouts_2018_100008",
      "email_subject": "You have a payout!",
      "email_message": "You have received a payout! Thanks for using our service!"
    },
    "payout_batch_id": "5UXD2E8A7EBQJ",
    "batch_status": "PENDING"
  }
}

Show payout batch details

GET/v1/payments/payouts/{payout_batch_id}

Shows the latest status of a batch payout. Includes the transaction status and other data for individual payout items.

Query parameters

fields
string
Shows details for only the specified fields.
page
integer
A non-zero integer representing the page of the results.
page_size
integer
The maximum number of results to return at one time. Value is a non-negative, non-zero integer. If the user chooses pagination, the maximum page is 1000.
total_required
boolean
Indicates whether to show the total items and total pages count in the response.

Path parameters

payout_batch_id
string
required
The ID of the payout for which to show details.

Sample Request

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

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that shows batch payout details.

total_items
integer
The total number of items in the full result list.
Maximum value: 15000.
total_pages
integer
The total number of pages.
Maximum value: 1000.
batch_header
object
A payout header. Includes the generated payout status.
items
array (contains the payout_batch_items object)
An array of individual items.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "batch_header": {
    "payout_batch_id": "FYXMPQTX4JC9N",
    "batch_status": "PROCESSING",
    "time_created": "2014-01-27T10:17:00Z",
    "time_completed": "2014-01-27T11:17:39.00Z",
    "sender_batch_header": {
      "sender_batch_id": "Payouts_2018_100009",
      "email_subject": "You have a payout!"
    },
    "amount": {
      "value": "438.35",
      "currency": "USD"
    },
    "fees": {
      "value": "5.84",
      "currency": "USD"
    }
  },
  "items": [
    {
      "payout_item_id": "DUCD8GC3VUKVE",
      "transaction_id": "6KA23440H1057442S",
      "transaction_status": "SUCCESS",
      "payout_batch_id": "FYXMPQTX4JC9N",
      "payout_item_fee": {
        "currency": "USD",
        "value": "1.00"
      },
      "payout_item": {
        "recipient_type": "EMAIL",
        "amount": {
          "value": "65.24",
          "currency": "USD"
        },
        "note": "Thanks for your patronage!",
        "receiver": "receiver@example.com",
        "sender_item_id": "14Feb_978"
      },
      "time_processed": "2014-01-27T10:18:32Z"
    },
    {
      "payout_item_id": "LGMEPRKTK7FQA",
      "transaction_id": "8K128187J1102003K",
      "transaction_status": "SUCCESS",
      "payout_batch_id": "FYXMPQTX4JC9N",
      "payout_item_fee": {
        "currency": "USD",
        "value": "1.00"
      },
      "payout_item": {
        "recipient_type": "EMAIL",
        "amount": {
          "value": "59.87",
          "currency": "USD"
        },
        "note": "Thanks for your patronage!",
        "receiver": "receiver2@example.com",
        "sender_item_id": "14Feb_321"
      },
      "time_processed": "2014-01-27T10:18:15Z"
    },
    {
      "payout_item_id": "BQ8GT9VG64EFS",
      "transaction_id": "57382391EC1682714",
      "transaction_status": "SUCCESS",
      "payout_batch_id": "FYXMPQTX4JC9N",
      "payout_item_fee": {
        "currency": "USD",
        "value": "1.00"
      },
      "payout_item": {
        "recipient_type": "EMAIL",
        "amount": {
          "value": "59.87",
          "currency": "USD"
        },
        "note": "Thanks for your patronage!",
        "receiver": "receiver3@example.com",
        "sender_item_id": "14Feb_239"
      },
      "time_processed": "2014-01-27T10:17:15Z"
    },
    {
      "payout_item_id": "LHKZN4VT93L2Q",
      "transaction_id": "1LG71547D1353984N",
      "transaction_status": "SUCCESS",
      "payout_batch_id": "FYXMPQTX4JC9N",
      "payout_item_fee": {
        "value": "USD",
        "currency": "0.75"
      },
      "payout_item": {
        "recipient_type": "EMAIL",
        "amount": {
          "value": "19.87",
          "currency": "USD"
        },
        "note": "Thanks for your patronage!",
        "receiver": "receiver4@example.com",
        "sender_item_id": "14Feb_235"
      },
      "time_processed": "2014-01-27T10:17:25Z"
    },
    {
      "payout_item_id": "4ZF3VZHHTQJG6",
      "transaction_id": "4BD48613EX3256543",
      "transaction_status": "SUCCESS",
      "payout_batch_id": "FYXMPQTX4JC9N",
      "payout_item_fee": {
        "currency": "USD",
        "value": "0.75"
      },
      "payout_item": {
        "recipient_type": "EMAIL",
        "amount": {
          "value": "9.87",
          "currency": "USD"
        },
        "note": "Thanks for your patronage!",
        "receiver": "receiver@example.com",
        "sender_item_id": "14Feb_234"
      },
      "time_processed": "2014-01-27T10:17:37Z"
    },
    {
      "payout_item_id": "DTCJCQ6LMH8JQ",
      "transaction_id": "25F63571CL9929422",
      "transaction_status": "SUCCESS",
      "payout_item_fee": {
        "currency": "USD",
        "value": "2.35"
      },
      "payout_batch_id": "FYXMPQTX4JC9N",
      "payout_item": {
        "recipient_type": "PHONE",
        "amount": {
          "value": "112.34",
          "currency": "USD"
        },
        "note": "Thanks for your support!",
        "receiver": "91-734-234-1234",
        "sender_item_id": "14Feb_235"
      },
      "time_processed": "2014-01-27T10:17:52Z"
    },
    {
      "payout_item_id": "GSBDQHUAUD44A",
      "transaction_id": "53R03517P98080414",
      "transaction_status": "SUCCESS",
      "payout_batch_id": "FYXMPQTX4JC9N",
      "payout_item_fee": {
        "currency": "USD",
        "value": "2.5"
      },
      "payout_item": {
        "recipient_type": "PHONE",
        "amount": {
          "value": "5.32",
          "currency": "USD"
        },
        "note": "Thanks for your patronage!",
        "receiver": "408X234-1234",
        "sender_item_id": "14Feb_235"
      },
      "time_processed": "2014-01-27T10:17:41Z"
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/FYXMPQTX4JC9N?page_size=1000&page=1",
      "method": "GET"
    }
  ]
}

Payouts item (resource group)

Use the /payouts-item resource to show payout item details and cancel an unclaimed payout item.

Show payout item details

GET/v1/payments/payouts-item/{payout_item_id}

Shows details for a payout item, by ID. A payout_item_id helps you identify denied payments. If a payment is denied, you can use the payout_item_id to identify the payment even if it lacks a transaction_id.

Path parameters

payout_item_id
string
required
The ID of the payout item for which to show details.

Sample Request

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

Response

A successful request returns the HTTP 200 OK status code and a JSON response body with a payout_item_details object, which contains data about a payout item including the transaction status.

payout_item_id
string
The ID for the payout item. Visible when you show details for a payout.
Maximum length: 30.
transaction_id
string
The PayPal-generated ID for the transaction.
Maximum length: 30.
activity_id
string
The unique PayPal-generated common ID that links the sender- and receiver-side transactions. Used for tracking.
Maximum length: 30.
transaction_status
enum
The transaction status.
The possible values are:
- SUCCESS. Funds have been credited to the recipient’s account.
- FAILED. This payout request has failed, so funds were not deducted from the sender’s account.
- PENDING. Your payout request was received and will be processed.
- UNCLAIMED. The recipient for this payout does not have a PayPal account. A link to sign up for a PayPal account was sent to the recipient. However, if the recipient does not claim this payout within 30 days, the funds are returned to your account.
- RETURNED. The recipient has not claimed this payout, so the funds have been returned to your account.
- ONHOLD. This payout request is being reviewed and is on hold.
- BLOCKED. This payout request has been blocked.
- REFUNDED. This payout request was refunded.
- REVERSED. This payout request was reversed.
payout_item_fee
object
The estimate for the payout fee. Initially, the fee is 0. The fee is populated after the item moves to the PENDING state
payout_batch_id
string
The PayPal-generated ID for the payout batch.
Maximum length: 30.
sender_batch_id
string
A sender-specified ID. Tracks the payout in an accounting system. Should be unique within 30 days.
Maximum length: 256.
payout_item
object
The sender-provided information for the payout item.
currency_conversion
object
The currency conversion applicable for this payout item.
time_processed
string
The date and time when this item was last processed, in Internet date and time format.
errors
object
The error details.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "payout_item_id": "8AELMXH8UB2P8",
  "transaction_id": "0C413693MN970190K",
  "activity_id": "0E158638XS0329106",
  "transaction_status": "SUCCESS",
  "payout_item_fee": {
    "currency": "USD",
    "value": "0.35"
  },
  "payout_batch_id": "Q8KVJG9TZTNN4",
  "payout_item": {
    "amount": {
      "value": "9.87",
      "currency": "USD"
    },
    "recipient_type": "EMAIL",
    "note": "Thanks for your patronage!",
    "receiver": "receiver@example.com",
    "sender_item_id": "14Feb_234"
  },
  "time_processed": "2018-01-27T10:17:41Z",
  "links": [
    {
      "rel": "self",
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts-item/8AELMXH8UB2P8",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/Q8KVJG9TZTNN4",
      "rel": "batch",
      "method": "GET"
    }
  ]
}

Cancel unclaimed payout item

POST/v1/payments/payouts-item/{payout_item_id}/cancel

Cancels an unclaimed payout item, by ID. If no one claims the unclaimed item within 30 days, the API automatically returns the funds to the sender. Use this call to cancel the unclaimed item before the automatic 30-day refund. You can cancel payout items with a transaction_status of UNCLAIMED.

Path parameters

payout_item_id
string
required
The ID of the payout item to cancel.

Sample Request

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

Response

A successful request returns the HTTP 200 OK status code with a JSON response body that shows payout item details.

payout_item_id
string
The ID for the payout item. Visible when you show details for a payout.
Maximum length: 30.
transaction_id
string
The PayPal-generated ID for the transaction.
Maximum length: 30.
activity_id
string
The unique PayPal-generated common ID that links the sender- and receiver-side transactions. Used for tracking.
Maximum length: 30.
transaction_status
enum
The transaction status.
The possible values are:
- SUCCESS. Funds have been credited to the recipient’s account.
- FAILED. This payout request has failed, so funds were not deducted from the sender’s account.
- PENDING. Your payout request was received and will be processed.
- UNCLAIMED. The recipient for this payout does not have a PayPal account. A link to sign up for a PayPal account was sent to the recipient. However, if the recipient does not claim this payout within 30 days, the funds are returned to your account.
- RETURNED. The recipient has not claimed this payout, so the funds have been returned to your account.
- ONHOLD. This payout request is being reviewed and is on hold.
- BLOCKED. This payout request has been blocked.
- REFUNDED. This payout request was refunded.
- REVERSED. This payout request was reversed.
payout_item_fee
object
The estimate for the payout fee. Initially, the fee is 0. The fee is populated after the item moves to the PENDING state
payout_batch_id
string
The PayPal-generated ID for the payout batch.
Maximum length: 30.
sender_batch_id
string
A sender-specified ID. Tracks the payout in an accounting system. Should be unique within 30 days.
Maximum length: 256.
payout_item
object
The sender-provided information for the payout item.
currency_conversion
object
The currency conversion applicable for this payout item.
time_processed
string
The date and time when this item was last processed, in Internet date and time format.
errors
object
The error details.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

Sample Response

{
  "payout_item_id": "5KUDKLF8SDC7S",
  "transaction_id": "1DG93452WK758815H",
  "activity_id": "0E158638XS0329101",
  "transaction_status": "RETURNED",
  "payout_item_fee": {
    "currency": "USD",
    "value": "0.35"
  },
  "payout_batch_id": "CQMWKDQF5GFLL",
  "sender_batch_id": "Payouts_2018_100006",
  "payout_item": {
    "recipient_type": "EMAIL",
    "amount": {
      "value": "9.87",
      "currency": "USD"
    },
    "note": "Thanks for your patronage!",
    "receiver": "receiver@example.com",
    "sender_item_id": "14Feb_234"
  },
  "time_processed": "2018-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-m.sandbox.paypal.com/v1/payments/payouts-item/5KUDKLF8SDC7S",
      "method": "GET"
    },
    {
      "rel": "batch",
      "href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/CQMWKDQF5GFLL",
      "method": "GET"
    }
  ]
}

Common object definitions

alternate_notification_method

phone
object
The mobile phone number of the receiver.

application_context

social_feed_privacy
string
This attribute controls the privacy of a payout transaction in recipient’s feed. PUBLIC, FRIENDS_ONLY & PRIVATE are the values that can be used. PUBLIC - The payment displays on the recipient's public Venmo feed. FRIENDS_ONLY - The payment displays only to the recipient's Venmo friends. PRIVATE - The payment displays only on the recipient's personal feed. Defaults to PRIVATE if left blank.
Maximum length: 15.
holler_url
string
Link to a Holler sticker. For Venmo recipients, the sticker displays with the payout message. The maximum URL length is 151.
logo_url
string
Link to a logo that displays as the sender's profile image in the recipient's Venmo feed. Used to add or update the business profile image. Max image size: 1024 x 1024 pixels. The image should be square and maximum URL length is 2000.

batch_status

batch_status
enum
The payouts status.
The possible values are:
- DENIED. Your payout requests were denied, so they were not processed. Check the error messages to see any steps necessary to fix these issues.
- PENDING. Your payout requests were received and will be processed soon.
- PROCESSING. Your payout requests were received and are now being processed.
- SUCCESS. Your payout batch was processed and completed. Check the status of each item for any holds or unclaimed transactions.
- CANCELED. The payouts file that was uploaded through the PayPal portal was cancelled by the sender.

create_payout_request

sender_batch_header
object
required
The sender-provided payout header for a payout request.
items
array (contains the payout_item object)
required
An array of individual payout items.
Minimum length: 1.
Maximum length: 15000.

currency

currency
string
required
The three-character ISO-4217 currency code.
value
string
required
The value, which might be:
- An integer for currencies like JPY that are not typically fractional.
- A decimal fraction for currencies like TND that are subdivided into thousandths.
For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

currency_code

currency_code
string
The three-character ISO-4217 currency code that identifies the currency.
Minimum length: 3.
Maximum length: 3.

error

name
string
required
The human-readable, unique name of the error.
message
string
required
The message that describes the error.
debug_id
string
required
The PayPal internal ID. Used for correlation purposes.
information_link
string
The information link, or URI, that shows detailed information about this error for the developer.
Read only.
details
array (contains the error_details object)
An array of additional details about the error.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

error

name
string
required
The human-readable, unique name of the error.
message
string
required
The message that describes the error.
debug_id
string
required
The PayPal internal ID. Used for correlation purposes.
information_link
string
The information link, or URI, that shows detailed information about this error for the developer.
Read only.
details
array (contains the error_details object)
An array of additional details about the error.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

error_details

field
string
The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
value
string
The value of the field that caused the error.
location
string
The location of the field that caused the error. Value is body, path, or query.
issue
string
required
The unique, fine-grained application-level error code.
description
string
The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.

error_details

field
string
The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
value
string
The value of the field that caused the error.
location
string
The location of the field that caused the error. Value is body, path, or query.
issue
string
required
The reason for the error.

funding_source

funding_source
enum
Identifies a funding source type.
The possible values are:
- BALANCE. Funded by balance.

language

language
string
The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code.
Minimum length: 2.
Maximum length: 10.
Pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$.

link_description

href
string
required
The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
rel
string
required
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
The HTTP method required to make the related call.
Possible values: GET,POST,PUT,DELETE,HEAD,CONNECT,OPTIONS,PATCH.

link_description

href
string
required
The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
rel
string
required
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
The HTTP method required to make the related call.
Possible values: GET,POST,PUT,DELETE,HEAD,CONNECT,OPTIONS,PATCH.

link_description

href
string
required
The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.
rel
string
required
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
The HTTP method required to make the related call.
Possible values: GET,POST,PUT,DELETE,HEAD,CONNECT,OPTIONS,PATCH.

name

prefix
string
The prefix, or title, to the party's name.
Maximum length: 140.
given_name
string
When the party is a person, the party's given, or first, name.
Maximum length: 140.
surname
string
When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.
Maximum length: 140.
middle_name
string
When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.
Maximum length: 140.
suffix
string
The suffix for the party's name.
Maximum length: 140.
alternate_full_name
string
DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.
Maximum length: 300.
full_name
string
When the party is a person, the party's full name.
Maximum length: 300.

name_validation

name_validation

payout

batch_header
object
The payout header.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

payout_batch

total_items
integer
The total number of items in the full result list.
Maximum value: 15000.
total_pages
integer
The total number of pages.
Maximum value: 1000.
batch_header
object
A payout header. Includes the generated payout status.
items
array (contains the payout_batch_items object)
An array of individual items.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

payout_batch_header

payout_batch_id
string
required
The PayPal-generated ID for a payout.
Maximum length: 30.
batch_status
enum
required
The PayPal-generated payout status. If the payout passes preliminary checks, the status is PENDING.
The possible values are:
- DENIED. Your payout requests were denied, so they were not processed. Check the error messages to see any steps necessary to fix these issues.
- PENDING. Your payout requests were received and will be processed soon.
- PROCESSING. Your payout requests were received and are now being processed.
- SUCCESS. Your payout batch was processed and completed. Check the status of each item for any holds or unclaimed transactions.
- CANCELED. The payouts file that was uploaded through the PayPal portal was cancelled by the sender.
time_created
string
The date and time when processing for the payout began, in Internet date and time format.
time_completed
string
The date and time when processing for the payout was completed, in Internet date and time format.
time_closed
string
The date and time when the payout was closed, in Internet date and time format. A payout is considered closed when all items in a batch are processed and the available balance from the temporary hold is released.
sender_batch_header
object
required
The original payout header, as provided by the payment sender.
funding_source
enum
The ID to differentiate a PayPal balance-funded transaction from a PayPal treasury-funded transaction.
The possible values are:
- BALANCE. Funded by balance.
amount
object
The currency and total amount requested for the payouts.
fees
object
The currency and amount of the total estimate for the applicable payouts fees. Initially, the fee is 0. The fee is populated after the payout moves to the PROCESSING state.

payout_batch_items

payout_item_id
string
required
The ID for the payout item. Viewable when you show details for a payout.
Maximum length: 30.
transaction_id
string
The PayPal-generated ID for the transaction.
Maximum length: 30.
activity_id
string
The unique PayPal-generated common ID created to link sender side and receiver side transaction. Used for tracking.
Maximum length: 30.
transaction_status
enum
The transaction status.
The possible values are:
- SUCCESS. Funds have been credited to the recipient’s account.
- FAILED. This payout request has failed, so funds were not deducted from the sender’s account.
- PENDING. Your payout request was received and will be processed.
- UNCLAIMED. The recipient for this payout does not have a PayPal account. A link to sign up for a PayPal account was sent to the recipient. However, if the recipient does not claim this payout within 30 days, the funds are returned to your account.
- RETURNED. The recipient has not claimed this payout, so the funds have been returned to your account.
- ONHOLD. This payout request is being reviewed and is on hold.
- BLOCKED. This payout request has been blocked.
- REFUNDED. This payout request was refunded.
- REVERSED. This payout request was reversed.
payout_item_fee
object
The fee, in U.S. dollars.
payout_batch_id
string
required
The PayPal-generated ID for the payout.
Maximum length: 30.
payout_item
object
required
The sender-provided information for the payout item.
currency_conversion
object
The currency conversion applicable for this payout item.
time_processed
string
The date and time when this item was last processed, in Internet date and time format.
errors
object
The error details.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

payout_currency_conversion

from_amount
object
The amount that is converted from.
to_amount
object
The amount that is converted to.
exchange_rate
string
The exchange rate that is applied for this payout.

payout_header

payout_batch_id
string
required
The PayPal-generated ID for a payout.
Maximum length: 30.
batch_status
enum
required
The PayPal-generated payout status. If the payout passes preliminary checks, the status is PENDING.
The possible values are:
- DENIED. Your payout requests were denied, so they were not processed. Check the error messages to see any steps necessary to fix these issues.
- PENDING. Your payout requests were received and will be processed soon.
- PROCESSING. Your payout requests were received and are now being processed.
- SUCCESS. Your payout batch was processed and completed. Check the status of each item for any holds or unclaimed transactions.
- CANCELED. The payouts file that was uploaded through the PayPal portal was cancelled by the sender.
time_created
string
The date and time when processing for the payout began, in Internet date and time format.
sender_batch_header
object
required
The original payout header, as provided by the payment sender.

payout_item

recipient_type
string
The recipient type. Value is:
- EMAIL. The unencrypted email. Value is a string of up to 127 single-byte characters.
- PHONE. The unencrypted phone number.
  Note: The PayPal sandbox does not support the PHONE recipient type.
- PAYPAL_ID. The encrypted PayPal account number.
If the sender_batch_header includes the recipient_type attribute, payout items use the recipient_type of the sender_batch_header, unless a payout item has its own recipient_type attribute. If the sender_batch_header omits the recipient_type attribute, each payout item must include its own recipient_type value.
Maximum length: 13.
amount
object
required
The currency and amount to pay the receiver.
note
string
The sender-specified note for notifications. Supports up to 4000 ASCII characters and 1000 non-ASCII characters.
Maximum length: 4000.
receiver
string
required
The receiver of the payment. Corresponds to the recipient_type value in the request. Max value of up to 127 single-byte characters.
Maximum length: 127.
sender_item_id
string
The sender-specified ID number. Tracks the payout in an accounting system.
Maximum length: 63.
recipient_wallet
string
The recipient wallet.
Maximum length: 36.
alternate_notification_method
object
Captures additional notification modes to reach out to the receiver regarding this payment.
notification_language
string
The language in which to show the payout recipient's email message. Used only when the recipient does not have a PayPal account. If you omit the language or provide invalid language and the recipient does not have a PayPal account, the email message is sent in the language of the merchant's PayPal account.
Minimum length: 2.
Maximum length: 10.
Pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$.
application_context
object
Metadata for accepting additional information from merchants to Venmo.

payout_item

payout_item_id
string
required
The ID for the payout item. Visible when you show details for a payout.
Maximum length: 30.
transaction_id
string
The PayPal-generated ID for the transaction.
Maximum length: 30.
activity_id
string
The unique PayPal-generated common ID that links the sender- and receiver-side transactions. Used for tracking.
Maximum length: 30.
transaction_status
enum
The transaction status.
The possible values are:
- SUCCESS. Funds have been credited to the recipient’s account.
- FAILED. This payout request has failed, so funds were not deducted from the sender’s account.
- PENDING. Your payout request was received and will be processed.
- UNCLAIMED. The recipient for this payout does not have a PayPal account. A link to sign up for a PayPal account was sent to the recipient. However, if the recipient does not claim this payout within 30 days, the funds are returned to your account.
- RETURNED. The recipient has not claimed this payout, so the funds have been returned to your account.
- ONHOLD. This payout request is being reviewed and is on hold.
- BLOCKED. This payout request has been blocked.
- REFUNDED. This payout request was refunded.
- REVERSED. This payout request was reversed.
payout_item_fee
object
The estimate for the payout fee. Initially, the fee is 0. The fee is populated after the item moves to the PENDING state
payout_batch_id
string
required
The PayPal-generated ID for the payout batch.
Maximum length: 30.
sender_batch_id
string
A sender-specified ID. Tracks the payout in an accounting system. Should be unique within 30 days.
Maximum length: 256.
payout_item
object
required
The sender-provided information for the payout item.
currency_conversion
object
The currency conversion applicable for this payout item.
time_processed
string
The date and time when this item was last processed, in Internet date and time format.
errors
object
The error details.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Read only.

payout_item_detail

recipient_type
enum
The ID type that identifies the payment receiver.
The possible values are:
- EMAIL. An unencrypted email. Value is a string of up to 127 single-byte characters.
- PHONE. An unencrypted phone number.
- PAYPAL_ID. An encrypted PayPal account number.
amount
object
required
The currency and amount of payout item. Might be an integer for currencies like JPY that are not typically fractional or a decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency codes - ISO 4217.
note
string
The sender-specified note for notifications. Supports up to 4000 ASCII characters and 1000 non-ASCII characters.
Maximum length: 4000.
receiver
string
required
The receiver of the payment. Corresponds to the recipient_type value in the request.
Maximum length: 127.
sender_item_id
string
A sender-specified ID number. Tracks the payout in an accounting system.
Maximum length: 63.
recipient_name
object
The name of the recipient where money is credited. For UNCLAIMED payments, the recipient name is populated after the payment is claimed.
recipient_wallet
enum
The recipient wallet.
The possible values are:
- PAYPAL. PayPal Wallet.
- VENMO. Venmo Wallet.
- RECIPIENT_SELECTED. Recipient selects how to receive payment from payment options.

payout_sender_batch_header

sender_batch_id
string
The sender-specified ID number. Tracks the payout in an accounting system.
Note:
PayPal does not process duplicate payouts. If you specify a sender_batch_id that was used in the last 30 days, the API rejects the request with an error message that shows the duplicate sender_batch_id and includes a HATEOAS link to the original payout with the same sender_batch_id.
If you receive an HTTP 5nn status code, you can safely retry the request with the same sender_batch_id. The API completes a payment only once for a sender_batch_id that is used within 30 days.
Maximum length: 256.
recipient_type
enum
The ID type that identifies the payment receiver.
The possible values are:
- EMAIL. An unencrypted email. Value is a string of up to 127 single-byte characters.
- PHONE. An unencrypted phone number.
- PAYPAL_ID. An encrypted PayPal account number.
email_subject
string
The subject line for the email that PayPal sends when payment for a payout item completes. The subject line is the same for all recipients. Value is an alphanumeric string with a maximum length of 255 single-byte characters.
Maximum length: 255.
email_message
string
The email message that PayPal sends when the payout item completes. The message is the same for all recipients.
Maximum length: 1000.

phone

country_code
string
required
The country calling code (CC), in its canonical international E.164 numbering plan format. The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
Minimum length: 1.
Maximum length: 3.
Pattern: ^[0-9]{1,3}?$.
national_number
string
required
The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN).
Minimum length: 1.
Maximum length: 14.
Pattern: ^[0-9]{1,14}?$.
extension_number
string
The extension number.
Minimum length: 1.
Maximum length: 15.
Pattern: ^[0-9]{1,15}?$.

recipient_type

recipient_type
enum
The ID type that identifies the payment receiver.
The possible values are:
- EMAIL. An unencrypted email. Value is a string of up to 127 single-byte characters.
- PHONE. An unencrypted phone number.
- PAYPAL_ID. An encrypted PayPal account number.

recipient_wallet

recipient_wallet
enum
The wallet where the recipient receives the payout. Payouts to Venmo recipients require a 'note' string and a US mobile phone number.
The possible values are:
- PAYPAL. PayPal Wallet.
- VENMO. Venmo Wallet.
- RECIPIENT_SELECTED. Recipient selects how to receive payment from payment options.

sender_batch_header

sender_batch_id
string
A sender-specified ID number. Tracks the payout in an accounting system.
Note:
PayPal does not process duplicate payouts. If you specify a sender_batch_id that was used in the last 30 days, the API rejects the request with an error message that shows the duplicate sender_batch_id and includes a HATEOAS link to the original payout with the same sender_batch_id.
If you receive an HTTP 5nn status code, you can safely retry the request with the same sender_batch_id. The API completes a payment only once for a sender_batch_id that is used within 30 days.
Maximum length: 256.
recipient_type
string
The ID type that identifies the recipient of the payment. For example, EMAIL.
Maximum length: 13.
email_subject
string
The subject line for the email that PayPal sends when payment for a payout item completes. The subject line is the same for all recipients. Value is an alphanumeric string of up to 255 single-byte characters.
Maximum length: 255.
email_message
string
The email message that PayPal sends when the payout item completes. The message is the same for all recipients.
Maximum length: 1000.
note
string
The payouts and item-level notes are concatenated in the email. The maximum combined length of the notes is 1000 characters.
Maximum length: 1000.

transaction_status

transaction_status
enum
The item transaction status.
The possible values are:
- SUCCESS. Funds have been credited to the recipient’s account.
- FAILED. This payout request has failed, so funds were not deducted from the sender’s account.
- PENDING. Your payout request was received and will be processed.
- UNCLAIMED. The recipient for this payout does not have a PayPal account. A link to sign up for a PayPal account was sent to the recipient. However, if the recipient does not claim this payout within 30 days, the funds are returned to your account.
- RETURNED. The recipient has not claimed this payout, so the funds have been returned to your account.
- ONHOLD. This payout request is being reviewed and is on hold.
- BLOCKED. This payout request has been blocked.
- REFUNDED. This payout request was refunded.
- REVERSED. This payout request was reversed.

Error messages

In addition to the common HTTP status codes that the REST APIs return, the Payouts API can return the following errors.

ACCOUNT_RESTRICTED
Access to your account has been restricted. Contact your account manager or our customer service team for assistance.
ACCOUNT_UNCONFIRMED_EMAIL
You need to be a verified PayPal account holder to send payouts. You can verify your account by confirming your email and your bank account or credit card. Contact your account manager or our customer service team for assistance.
AUTHORIZATION_ERROR
Your account is not authorized to use payouts. Contact your account manager or our customer service team for assistance.
BATCH_NOT_COMPLETED
This payout batch is still being processed. Please try again later.
CLOSED_MARKET
This account is not allowed to receive payouts from other countries. Try re-sending this payout to another account.
CURRENCY_COMPLIANCE
Due to currency compliance regulations, you are not allowed to make this transaction.
CURRENCY_NOT_SUPPORTED_FOR_RECEIVER
This currency cannot be accepted for this recipient’s account. You can re-send this payout with a different currency.
DUPLICATE_ITEM
This transaction is duplicated in this batch. Please check the Ref_ID / Sender_Item_ID.
GAMER_FAILED_COUNTRY_OF_RESIDENCE_CHECK
The recipient lives in a country that is not allowed to accept this payout.
GAMER_FAILED_FUNDING_SOURCE_CHECK
The funding source that was selected for this payout is not allowed. Try again by using your PayPal balance instead.
GAMING_INVALID_PAYMENT_FLOW
This payment flow is not allowed for gaming merchant accounts.
INSUFFICIENT_FUNDS
You have insufficient funds in your PayPal balance. You'll need to add funds to your account to complete the payout.
INTERNAL_ERROR
An error occurred while processing this payout request. Please re-submit this payout as a new batch or file.
ITEM_ALREADY_CANCELLED
This payout request has already been cancelled.
ITEM_CANCELLATION_FAILED
An error occurred while processing this payout request. Try again in a few minutes.
ITEM_INCORRECT_STATUS
You can only cancel items that are unclaimed.
VALIDATION_ERROR
JSON request is malformed. Check your request format and try again.
NEGATIVE_BALANCE
You have insufficient funds in your PayPal balance. You'll need to add funds to your account to complete the payout.
NON_HOLDING_CURRENCY
Your account does not have a PayPal balance in this currency. Try again with a currency that has funds in your PayPal account, or change your account settings to this currency.
PENDING_RECIPIENT_NON_HOLDING_CURRENCY_PAYMENT_PREFERENCE
This payout is pending because the recipient has set their account preferences to review credits in this currency. The recipient has been notified. Check back later for the status of this payout.
POS_LIMIT_EXCEEDED
You have exceeded the POS cumulative spending limit. Contact your account manager or our customer service team for assistance.
RATE_LIMIT_VALIDATION_FAILURES
Your request has been blocked due to multiple failed attempts. Please try again later.
RECEIVER_ACCOUNT_LOCKED
We were not able to send a payout because the recipient’s account is inactive or restricted. Funds have been returned to your account.
RECEIVER_COUNTRY_NOT_ALLOWED
We can’t send this payout because the recipient lives in a country where payouts are not allowed.
RECEIVER_STATE_RESTRICTED
We can’t send this payout because the recipient lives in a state where payouts are not allowed.
RECEIVER_UNCONFIRMED
The recipient’s email or phone number is unconfirmed. Any payments made to this account will be marked as Unclaimed until the recipient confirms their account information. Funds will be returned to your account if they are not claimed within 30 days.
RECEIVER_UNREGISTERED
The recipient for this payout does not have an account. A link to sign up for an account was sent to the recipient. However, if the recipient does not claim this payout within 30 days, the funds will be returned to your account.
RECEIVER_ACCOUNT_LIMITATION
The recipient's account is currently under limitation. Any payments made to this account will be on hold until the issue is resolved. Funds will be returned to your account if the limitation is not resolved within 30 days of the sent payout.
RECEIVER_YOUTH_ACCOUNT
We were not able to send a payout because the recipient has a youth account. Please check with the recipient for an alternate account to receive the payout.
RECEIVING_LIMIT_EXCEEDED
The recipient cannot accept this payout, because it exceeds the amount they can receive at this time. Please resubmit your payout request for a different amount.
REFUSED_ACCESS_DENIED
Your account is not allowed to send money. Check with your primary account holder to get permission to send money.
RECEIVER_REFUSED
The recipient has refused this payout in this currency. Try resending in a different currency.
REGULATORY_BLOCKED
This transaction is blocked due to regulatory compliance restrictions.
REGULATORY_PENDING
This transaction is pending, while it is reviewed for compliance with government regulations.
REQUIRED_SCOPE_MISSING
The access token doesn't have the required scope. You'll need to use the access token with the correct scope to send a payout.
RISK_DECLINE
This transaction was declined due to risk concerns.
SELF_PAY_NOT_ALLOWED
You can’t send a payout to yourself. Try sending it to a different account.
SENDER_ACCOUNT_LOCKED
You can’t send a payout now, because your account is locked or inactive. Contact your account manager or our customer service team for assistance.
SENDER_ACCOUNT_UNVERIFIED
To send a payout, you need to have a verified PayPal account. You can verify your account by confirming your bank account or credit card. Contact your account manager or our customer service team for assistance.
SENDER_STATE_RESTRICTED
Your address is in a state where payouts are not allowed. Contact your account manager or our customer service team for assistance.
SPENDING_LIMIT_EXCEEDED
You’ve exceeded your spending limit. Contact your account manager or our customer service team for assistance.
TRANSACTION_DECLINED_BY_TRAVEL_RULE
Your payout request does not comply with travel rule regulations. To send this payout, you’ll need to update and verify your account information. Contact your account manager or our customer service team for assistance.
TRANSACTION_LIMIT_EXCEEDED
This payout request has exceeded the limit for this type of transaction. The funds have been returned to your account.
UNDEFINED
An error occurred while processing this payout request. Try again in a few minutes, or try resending as part of a new request or file.
UNVERIFIED_RECIPIENT_NOT_SUPPORTED
This payout request was not completed because the recipient has not verified their account. Your account is only allowed to send payout to verified accounts.
USER_BUSINESS_ERROR
An error occurred while processing this payout request. For batch processing, try again with a different sender_batch_ID. For single payout items, try again with email or payer ID as recipient type.
USER_COUNTRY_NOT_ALLOWED
Your address is in a country where payouts are not allowed. Contact your account manager or our customer service team for assistance.
USER_FUNDING_SOURCE_INELIGIBLE
The funding source for this payout is not allowed. Try again by using your PayPal balance instead.
ZERO_AMOUNT
Please provide a valid payment amount.
APPROVER_DENIED
Payout request rejected by the approver. Please check with your approver.
INVALID_EMAIL
Email Address doesn’t exist. Try again with the correct Email Id.

PayPal Commerce Platform for Business

PayPal Commerce Platform for Marketplaces and Platforms

PayPal Commerce Platform for Enterprise

Docs Catalog

Reference

Developer Tools

Regional Codes

PayPal-Request-Id

sender_batch_header

items

Sample Request

batch_header

links

Sample Response

fields

page

page_size

total_required

payout_batch_id

Sample Request

total_items

total_pages

batch_header

items

links

Sample Response

payout_item_id

Sample Request

payout_item_id

transaction_id

activity_id

transaction_status

payout_item_fee

payout_batch_id

sender_batch_id

payout_item

currency_conversion

time_processed

errors

links

Sample Response

payout_item_id

Sample Request

payout_item_id

transaction_id

activity_id

transaction_status

payout_item_fee

payout_batch_id

sender_batch_id

payout_item

currency_conversion

time_processed

errors

links

Sample Response

phone

social_feed_privacy

holler_url

logo_url

batch_status

sender_batch_header

items

currency

value

currency_code

name

message

debug_id

information_link

details

links

name

message

debug_id

information_link

details

links

field

value

`PayPal-Request-Id`

`sender_batch_header`

`items`

`batch_header`

`links`

`fields`

`page`

`page_size`

`total_required`

`payout_batch_id`

`total_items`

`total_pages`

`batch_header`

`items`

`links`

`payout_item_id`

`payout_item_id`

`transaction_id`

`activity_id`

`transaction_status`

`payout_item_fee`

`payout_batch_id`

`sender_batch_id`

`payout_item`

`currency_conversion`

`time_processed`

`errors`

`links`

`payout_item_id`

`payout_item_id`

`transaction_id`

`activity_id`

`transaction_status`

`payout_item_fee`

`payout_batch_id`

`sender_batch_id`

`payout_item`

`currency_conversion`

`time_processed`

`errors`

`links`

`phone`

`social_feed_privacy`

`holler_url`

`logo_url`

`batch_status`

`sender_batch_header`

`items`

`currency`

`value`

`currency_code`

`name`

`message`

`debug_id`

`information_link`

`details`

`links`

`name`

`message`

`debug_id`

`information_link`

`details`

`links`

`field`

`value`

`location`

`issue`

`description`

`field`

`value`

`location`

`issue`

`funding_source`

`language`

`href`

`rel`

`method`

`href`

`rel`

`method`