Payouts API
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
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 duplicatesender_batch_id
and includes a HATEOAS link to the original payout with the samesender_batch_id
.
If you receive an HTTP5nn
status code, you can safely retry the request with the samesender_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 thePayPal-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
An array of individual payout items.
The sender-provided payout header for a payout request.
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
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
The payout header.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
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
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
200 OK
status code and a JSON response body that shows batch payout details.batch_header
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.
total_items
integer
The total number of items in the full result list.
total_pages
integer
The total number of pages.
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
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
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.activity_id
string
The unique PayPal-generated common ID that links the sender- and receiver-side transactions. Used for tracking.
currency_conversion
The currency conversion applicable for this payout item.
errors
The error details.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
payout_batch_id
string
The PayPal-generated ID for the payout batch.
payout_item
The sender-provided information for the payout item.
payout_item_fee
The estimate for the payout fee. Initially, the fee is
0
. The fee is populated after the item moves to thePENDING
statepayout_item_id
string
The ID for the payout item. Visible when you show details for a payout.
sender_batch_id
string
A sender-specified ID. Tracks the payout in an accounting system. Should be unique within 30 days.
time_processed
string
The date and time when this item was last processed, in Internet date and time format.
transaction_id
string
The PayPal-generated ID for the transaction.
transaction_status
enum
The item transaction status.
Note: For
POST/v1/payments/payouts-item/{payout_item_id}/cancel
, the only possibletransaction_status
value isRETURNED
.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
. Payout request has been submitted and is being processed. Recipient will get the funds once the request is processed successfully, else the funds will be returned to you.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
. Funds have been returned to your account. This can be because the recipient has not claimed this payout, or you have cancelled the payout.ONHOLD
. This payout request is being reviewed and is on hold.BLOCKED
. This payout request has been blocked.REFUNDED
. Funds have been refunded back to your account. This is because the recipient(PayPal Business verified account) has issued a refund for the payout initiated by you.REVERSED
. This payout request was reversed. This status is specific to web uploads.
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
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
200 OK
status code with a JSON response body that shows payout item details.activity_id
string
The unique PayPal-generated common ID that links the sender- and receiver-side transactions. Used for tracking.
currency_conversion
The currency conversion applicable for this payout item.
errors
The error details.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
payout_batch_id
string
The PayPal-generated ID for the payout batch.
payout_item
The sender-provided information for the payout item.
payout_item_fee
The estimate for the payout fee. Initially, the fee is
0
. The fee is populated after the item moves to thePENDING
statepayout_item_id
string
The ID for the payout item. Visible when you show details for a payout.
sender_batch_id
string
A sender-specified ID. Tracks the payout in an accounting system. Should be unique within 30 days.
time_processed
string
The date and time when this item was last processed, in Internet date and time format.
transaction_id
string
The PayPal-generated ID for the transaction.
transaction_status
enum
The item transaction status.
Note: For
POST/v1/payments/payouts-item/{payout_item_id}/cancel
, the only possibletransaction_status
value isRETURNED
.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
. Payout request has been submitted and is being processed. Recipient will get the funds once the request is processed successfully, else the funds will be returned to you.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
. Funds have been returned to your account. This can be because the recipient has not claimed this payout, or you have cancelled the payout.ONHOLD
. This payout request is being reviewed and is on hold.BLOCKED
. This payout request has been blocked.REFUNDED
. Funds have been refunded back to your account. This is because the recipient(PayPal Business verified account) has issued a refund for the payout initiated by you.REVERSED
. This payout request was reversed. This status is specific to web uploads.
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
The mobile phone number of the receiver.
application_context
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.
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.
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
An array of individual payout items.
The sender-provided payout header for a payout request.
currency
currency
string
required
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.
- An integer for currencies like
currency_code
currency_code
string
The three-character ISO-4217 currency code that identifies the currency.
error
debug_id
string
required
The PayPal internal ID. Used for correlation purposes.
message
string
required
The message that describes the error.
name
string
required
The human-readable, unique name of the error.
details
array (contains the error_details object)
An array of additional details about the error.
information_link
string
The information link, or URI, that shows detailed information about this error for the developer.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
error
debug_id
string
required
The PayPal internal ID. Used for correlation purposes.
message
string
required
The message that describes the error.
name
string
required
The human-readable, unique name of the error.
details
array (contains the error_details object)
An array of additional details about the error.
information_link
string
The information link, or URI, that shows detailed information about this error for the developer.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
error_details
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.
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.
location
string
The location of the field that caused the error. Value is
body
,path
, orquery
.value
string
The value of the field that caused the error.
error_details
issue
string
required
The reason for the error.
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.
location
string
The location of the field that caused the error. Value is
body
,path
, orquery
.value
string
The value of the field that caused 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.
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. Thehref
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.
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. Thehref
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.
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. Thehref
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.
name
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.
full_name
string
When the party is a person, the party's full name.
given_name
string
When the party is a person, the party's given, or first, name.
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.
prefix
string
The prefix, or title, to the party's name.
suffix
string
The suffix for the party's name.
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.
name_validation
name_validation
payout
batch_header
The payout header.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
payout_batch
batch_header
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.
total_items
integer
The total number of items in the full result list.
total_pages
integer
The total number of pages.
payout_batch_header
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.
payout_batch_id
string
required
The PayPal-generated ID for a payout.
The original payout header, as provided by the payment sender.
amount
The currency and total amount requested for the payouts.
fees
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 thePROCESSING
state.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.
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.
time_completed
string
The date and time when processing for the payout was completed, in Internet date and time format.
time_created
string
The date and time when processing for the payout began, in Internet date and time format.
payout_batch_items
payout_batch_id
string
required
The PayPal-generated ID for the payout.
The sender-provided information for the payout item.
payout_item_id
string
required
The ID for the payout item. Viewable when you show details for a payout.
activity_id
string
The unique PayPal-generated common ID created to link sender side and receiver side transaction. Used for tracking.
currency_conversion
The currency conversion applicable for this payout item.
errors
The error details.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
payout_item_fee
The fee, in U.S. dollars.
time_processed
string
The date and time when this item was last processed, in Internet date and time format.
transaction_id
string
The PayPal-generated ID for the transaction.
transaction_status
enum
The item transaction status.
Note: For
POST/v1/payments/payouts-item/{payout_item_id}/cancel
, the only possibletransaction_status
value isRETURNED
.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
. Payout request has been submitted and is being processed. Recipient will get the funds once the request is processed successfully, else the funds will be returned to you.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
. Funds have been returned to your account. This can be because the recipient has not claimed this payout, or you have cancelled the payout.ONHOLD
. This payout request is being reviewed and is on hold.BLOCKED
. This payout request has been blocked.REFUNDED
. Funds have been refunded back to your account. This is because the recipient(PayPal Business verified account) has issued a refund for the payout initiated by you.REVERSED
. This payout request was reversed. This status is specific to web uploads.
payout_header
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.
payout_batch_id
string
required
The PayPal-generated ID for a payout.
The original payout header, as provided by the payment sender.
time_created
string
The date and time when processing for the payout began, in Internet date and time format.
payout_item
The currency and amount to pay the receiver.
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.alternate_notification_method
Captures additional notification modes to reach out to the receiver regarding this payment.
application_context
Metadata for accepting additional information from merchants to Venmo.
note
string
The sender-specified note for notifications. Supports up to 4000 ASCII characters and 1000 non-ASCII characters.
notification_language
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.
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.USER_HANDLE
. User handle (or) Username associated with Venmo account.
If thesender_batch_header
includes therecipient_type
attribute, payout items use therecipient_type
of thesender_batch_header
, unless a payout item has its ownrecipient_type
attribute. If thesender_batch_header
omits therecipient_type
attribute, each payout item must include its ownrecipient_type
value.recipient_wallet
string
The recipient wallet.
sender_item_id
string
The sender-specified ID number. Tracks the payout in an accounting system.
payout_item
payout_batch_id
string
required
The PayPal-generated ID for the payout batch.
The sender-provided information for the payout item.
payout_item_id
string
required
The ID for the payout item. Visible when you show details for a payout.
activity_id
string
The unique PayPal-generated common ID that links the sender- and receiver-side transactions. Used for tracking.
currency_conversion
The currency conversion applicable for this payout item.
errors
The error details.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
payout_item_fee
The estimate for the payout fee. Initially, the fee is
0
. The fee is populated after the item moves to thePENDING
statesender_batch_id
string
A sender-specified ID. Tracks the payout in an accounting system. Should be unique within 30 days.
time_processed
string
The date and time when this item was last processed, in Internet date and time format.
transaction_id
string
The PayPal-generated ID for the transaction.
transaction_status
enum
The item transaction status.
Note: For
POST/v1/payments/payouts-item/{payout_item_id}/cancel
, the only possibletransaction_status
value isRETURNED
.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
. Payout request has been submitted and is being processed. Recipient will get the funds once the request is processed successfully, else the funds will be returned to you.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
. Funds have been returned to your account. This can be because the recipient has not claimed this payout, or you have cancelled the payout.ONHOLD
. This payout request is being reviewed and is on hold.BLOCKED
. This payout request has been blocked.REFUNDED
. Funds have been refunded back to your account. This is because the recipient(PayPal Business verified account) has issued a refund for the payout initiated by you.REVERSED
. This payout request was reversed. This status is specific to web uploads.
payout_item_detail
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 likeTND
that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency codes - ISO 4217.receiver
string
required
The receiver of the payment. Corresponds to the
recipient_type
value in the request.note
string
The sender-specified note for notifications. Supports up to 4000 ASCII characters and 1000 non-ASCII characters.
recipient_name
The name of the recipient where money is credited. For
UNCLAIMED
payments, the recipient name is populated after the payment is claimed.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
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.
sender_item_id
string
A sender-specified ID number. Tracks the payout in an accounting system.
payout_sender_batch_header
email_message
string
The email message that PayPal sends when the payout item completes. The message is the same for all recipients.
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.
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.
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 duplicatesender_batch_id
and includes a HATEOAS link to the original payout with the samesender_batch_id
.If you receive an HTTP
5nn
status code, you can safely retry the request with the samesender_batch_id
. The API completes a payment only once for asender_batch_id
that is used within 30 days.
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).
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).
extension_number
string
The extension number.
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
email_message
string
The email message that PayPal sends when the payout item completes. The message is the same for all recipients.
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.
note
string
The payouts and item-level notes are concatenated in the email. The maximum combined length of the notes is 1000 characters.
recipient_type
string
The ID type that identifies the recipient of the payment. For example,
EMAIL
.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 duplicatesender_batch_id
and includes a HATEOAS link to the original payout with the samesender_batch_id
.If you receive an HTTP
5nn
status code, you can safely retry the request with the samesender_batch_id
. The API completes a payment only once for asender_batch_id
that is used within 30 days.
transaction_status
transaction_status
enum
The item transaction status.
Note: For
POST/v1/payments/payouts-item/{payout_item_id}/cancel
, the only possibletransaction_status
value isRETURNED
.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
. Payout request has been submitted and is being processed. Recipient will get the funds once the request is processed successfully, else the funds will be returned to you.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
. Funds have been returned to your account. This can be because the recipient has not claimed this payout, or you have cancelled the payout.ONHOLD
. This payout request is being reviewed and is on hold.BLOCKED
. This payout request has been blocked.REFUNDED
. Funds have been refunded back to your account. This is because the recipient(PayPal Business verified account) has issued a refund for the payout initiated by you.REVERSED
. This payout request was reversed. This status is specific to web uploads.
Additional API information
Error messages
In addition to the common HTTP status codes that the REST APIs return, the Payouts API can return the following errors.