Payouts(1)

?This API is currently not supported by our SDK

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 Payouts Reporting. The Payouts API uses the ISO 8601 Internet date and time format.

operation/payouts.post Create batch payout

post/v1/payments/payouts

Try it

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.

SecurityOauth2

Request

header Parameters


PayPal-Request-Id	string[ 1 .. 1000 ] characters^.*$ The server stores keys for 30 days.

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json


items required	Array of objects (payout_item_request) [ 1 .. 15000 ] items An array of individual payout items.
sender_batch_header required	object (sender_batch_header) The sender-provided payout header for a payout request.

Responses

201 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.

Request samples

Payload
cURL

application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Sample 1 - 201 - Create Batch PayoutSample 1 - 201 - Create Batch Payout

Copy

Expand allCollapse all

`{"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",

"purpose": "GOODS"

}

]

Response samples

application/json

Sample 1 - 201 - Create Batch PayoutSample 1 - 201 - Create Batch Payout

Copy

Expand allCollapse all

`{"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"

}

operation/payouts.get Show payout batch details

get/v1/payments/payouts/

Try it

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

SecurityOauth2

Request

path Parameters


id required	string[ 1 .. 1000 ] characters^.*$ The ID of the payout for which to show details.

query Parameters


fields	string[ 1 .. 1000 ] characters^.*$ Shows details for only the specified fields.
page	integer[ 0 .. 1000 ] Default:1 A non-zero integer representing the page of the results.
page_size	integer[ 0 .. 1000 ] 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 Default:false Indicates whether to show the total items and total pages count in the response.

Responses

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

Request samples

cURL

Copy

curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/payouts/LEP6947CGTKRL?page=1&page_size=5&total_required=true \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer A101.OLQiCyqOpVwigKMNpe3CYlamZ1KTKQmhrbAZK85RIy4IiWh9d_up_lTkhf_lfXdV.P3gvkY3PO28akjKYaDorm12QdfK'

Response samples

application/json

Sample 1 - 200 - Show Details for Batch PayoutSample 1 - 200 - Show Details for Batch Payout

Copy

Expand allCollapse all

`{"total_items": 11,

"total_pages": 3,

"batch_header": {"payout_batch_id": "LEP6947CGTKRL",

"batch_status": "SUCCESS",

"time_created": "2018-03-13T12:44:47Z",

"time_completed": "2018-03-13T12:44:55Z",

"time_closed": "2018-03-13T12:44:55Z",

"sender_batch_header": {"email_subject": "You got a Test"

"amount": {"currency": "USD",

"value": "550.0"

"fees": {"currency": "USD",

"value": "2.75"

"displayable": true

"items": [{"payout_item_id": "5MYSR9GT8AEUG",

"transaction_id": "2JE19762AW167960J",

"activity_id": "0E158638XS0329103",

"transaction_status": "SUCCESS",

"payout_item_fee": {"currency": "USD",

"value": "0.25"

},

"payout_batch_id": "LEP6947CGTKRL",

"payout_item": {"recipient_type": "PHONE",

"amount": {"currency": "USD",

"value": "50.0"

},

"note": "Mr. Rob",

"receiver": "93847858694",

"sender_item_id": "X1"

},

"time_processed": "2018-03-13T12:44:51Z",

"links": [{"href": "https://api-m.sandbox.paypal.com/v1/payments/payouts-item/5MYSR9GT8AEUG",

"rel": "item",

"method": "GET"

}

]

},

{"payout_item_id": "ZV967ZUVUGL9L",

"transaction_id": "8JG30981BP6452334",

"activity_id": "0E158638XS0329102",

"transaction_status": "SUCCESS",

"payout_item_fee": {"currency": "USD",

"value": "0.25"

},

"payout_batch_id": "LEP6947CGTKRL",

"payout_item": {"recipient_type": "PHONE",

"amount": {"currency": "USD",

"value": "50.0"

},

"note": "Mr. Rob",

"receiver": "93847838694",

"sender_item_id": "X12"

},

"time_processed": "2018-03-13T12:44:51Z",

"links": [{"href": "https://api-m.sandbox.paypal.com/v1/payments/payouts-item/ZV967ZUVUGL9L",

"rel": "item",

"method": "GET"

}

]

},

{"payout_item_id": "7X73FYJYFQGES",

"transaction_id": "8S043803CK444682D",

"activity_id": "0E158638XS0329101",

"transaction_status": "SUCCESS",

"payout_item_fee": {"currency": "USD",

"value": "0.25"

},

"payout_batch_id": "LEP6947CGTKRL",

"payout_item": {"recipient_type": "PHONE",

"amount": {"currency": "USD",

"value": "50.0"

},

"note": "Mr. Rob",

"receiver": "92847858694",

"sender_item_id": "X13"

},

"time_processed": "2018-03-13T12:44:54Z",

"links": [{"href": "https://api-m.sandbox.paypal.com/v1/payments/payouts-item/7X73FYJYFQGES",

"rel": "item",

"method": "GET"

}

]

},

{"payout_item_id": "KBN2UQVSP8YDA",

"transaction_id": "13947164DM210580M",

"activity_id": "0E158638XS0329109",

"transaction_status": "SUCCESS",

"payout_item_fee": {"currency": "USD",

"value": "0.25"

},

"payout_batch_id": "LEP6947CGTKRL",

"payout_item": {"recipient_type": "PHONE",

"amount": {"currency": "USD",

"value": "50.0"

},

"note": "Mr. Rob",

"receiver": "93847878694",

"sender_item_id": "X14"

},

"time_processed": "2018-03-13T12:44:55Z",

"links": [{"href": "https://api-m.sandbox.paypal.com/v1/payments/payouts-item/KBN2UQVSP8YDA",

"rel": "item",

"method": "GET"

}

]

},

{"payout_item_id": "X74HTBHMHAVG2",

"transaction_id": "30E82346NA368651S",

"transaction_status": "SUCCESS",

"activity_id": "0E158638XS0329108",

"payout_item_fee": {"currency": "USD",

"value": "0.25"

},

"payout_batch_id": "LEP6947CGTKRL",

"payout_item": {"recipient_type": "PHONE",

"amount": {"currency": "USD",

"value": "50.0"

},

"note": "Mr. Rob",

"receiver": "93847828694",

"sender_item_id": "X15"

},

"time_processed": "2018-03-13T12:44:51Z",

"links": [{"href": "https://api-m.sandbox.paypal.com/v1/payments/payouts-item/X74HTBHMHAVG2",

"rel": "item",

"method": "GET"

}

]

}

],

"links": [{"href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/LEP6947CGTKRL?page_size=5&page=2",

"rel": "next",

"method": "GET"

},

{"href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/LEP6947CGTKRL?page_size=5&page=3",

"rel": "last",

"method": "GET"

},

{"href": "https://api-m.sandbox.paypal.com/v1/payments/payouts/LEP6947CGTKRL?page_size=5&page=1",

"rel": "self",

"method": "GET"

}

]

operation/payouts-item.get Show payout item details

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

Try it

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.

SecurityOauth2

Request

path Parameters


payout_item_id required	string[ 1 .. 32 ] characters^.*$ The ID of the payout item for which to show details.

Responses

200 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.

Request samples

cURL

Copy

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

Response samples

application/json

Sample 1 - 200 - Show Payout Item DetailsSample 1 - 200 - Show Payout Item Details

Copy

Expand allCollapse all

`{"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"

}

]

operation/payouts-item.cancel Cancel unclaimed payout item

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

Try it

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.

SecurityOauth2

Request

path Parameters


payout_item_id required	string[ 1 .. 32 ] characters^.*$ The ID of the payout item to cancel.

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

any

Responses

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

Request samples

Payload
cURL

application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Sample 1 - 200 - Cancel Unclaimed Payout ItemSample 1 - 200 - Cancel Unclaimed Payout Item

Copy

{ }

Response samples

application/json

Sample 1 - 200 - Cancel Unclaimed Payout ItemSample 1 - 200 - Cancel Unclaimed Payout Item

Copy

Expand allCollapse all

`{"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"

}

]

tag/Errors Errors

section/ACCOUNT_RESTRICTED ACCOUNT_RESTRICTED

Message:

Access to your account has been restricted. Contact your account manager or our customer service team for assistance.

section/ACCOUNT_UNCONFIRMED_EMAIL ACCOUNT_UNCONFIRMED_EMAIL

Message:

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.

section/APPROVER_DENIED APPROVER_DENIED

Message:

Payout request rejected by the approver. Please check with your approver.

section/AUTHORIZATION_ERROR AUTHORIZATION_ERROR

Message:

Your account is not authorized to use payouts. Contact your account manager or our customer service team for assistance.

section/BATCH_NOT_COMPLETED BATCH_NOT_COMPLETED

Message:

This payout batch is still being processed. Please try again later.

section/CLOSED_MARKET CLOSED_MARKET

Message:

This account is not allowed to receive payouts from other countries. Try re-sending this payout to another account.

section/CURRENCY_COMPLIANCE CURRENCY_COMPLIANCE

Message:

Due to currency compliance regulations, you are not allowed to make this transaction.

section/CURRENCY_NOT_SUPPORTED_FOR_RECEIVER CURRENCY_NOT_SUPPORTED_FOR_RECEIVER

Message:

This currency cannot be accepted for this recipient’s account. You can re-send this payout with a different currency.

section/DUPLICATE_ITEM DUPLICATE_ITEM

Message:

This transaction is duplicated in this batch. Please check the Ref_ID / Sender_Item_ID.

section/GAMER_FAILED_COUNTRY_OF_RESIDENCE_CHECK GAMER_FAILED_COUNTRY_OF_RESIDENCE_CHECK

Message:

The recipient lives in a country that is not allowed to accept this payout.

section/GAMER_FAILED_FUNDING_SOURCE_CHECK GAMER_FAILED_FUNDING_SOURCE_CHECK

Message:

The funding source that was selected for this payout is not allowed. Try again by using your PayPal balance instead.

section/GAMING_INVALID_PAYMENT_FLOW GAMING_INVALID_PAYMENT_FLOW

Message:

This payment flow is not allowed for gaming merchant accounts.

section/INSUFFICIENT_FUNDS INSUFFICIENT_FUNDS

Message:

You have insufficient funds in your PayPal balance. You'll need to add funds to your account to complete the payout.

section/INTERNAL_ERROR INTERNAL_ERROR

Message:

An error occurred while processing this payout request. Please re-submit this payout as a new batch or file.

section/INVALID_EMAIL INVALID_EMAIL

Message:

Email Address doesn’t exist. Try again with the correct Email Id.

section/ITEM_ALREADY_CANCELLED ITEM_ALREADY_CANCELLED

Message:

This payout request has already been cancelled.

section/ITEM_CANCELLATION_FAILED ITEM_CANCELLATION_FAILED

Message:

An error occurred while processing this payout request. Try again in a few minutes.

section/ITEM_INCORRECT_STATUS ITEM_INCORRECT_STATUS

Message:

You can only cancel items that are unclaimed.

section/NEGATIVE_BALANCE NEGATIVE_BALANCE

Message:

You have insufficient funds in your PayPal balance. You'll need to add funds to your account to complete the payout.

section/NON_HOLDING_CURRENCY NON_HOLDING_CURRENCY

Message:

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.

section/PENDING_RECIPIENT_NON_HOLDING_CURRENCY_PAYMENT_PREFERENCE PENDING_RECIPIENT_NON_HOLDING_CURRENCY_PAYMENT_PREFERENCE

Message:

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.

section/PHONE_NUMBER_INVALID PHONE_NUMBER_INVALID

Message:

We were unable to deliver the Payout SMS to this recipient. This might be due to an invaild or incorrect phone number. Any amount deducted from this account will be returned shortly.

section/PHONE_NUMBER_SMS_OPTOUT PHONE_NUMBER_SMS_OPTOUT

Message:

The receiver of this payout has opted out of PayPal SMS services. We were unable to deliver the payout SMS for the receiver to claim. Any amount deducted from this account will be returned shortly.

section/POS_LIMIT_EXCEEDED POS_LIMIT_EXCEEDED

Message:

You have exceeded the POS cumulative spending limit. Contact your account manager or our customer service team for assistance.

section/RATE_LIMIT_VALIDATION_FAILURES RATE_LIMIT_VALIDATION_FAILURES

Message:

Your request has been blocked due to multiple failed attempts. Please try again later.

section/RECEIVER_ACCOUNT_LIMITATION RECEIVER_ACCOUNT_LIMITATION

Message:

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.

Description: 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.

section/RECEIVER_ACCOUNT_LOCKED RECEIVER_ACCOUNT_LOCKED

Message:

We were not able to send a payout because the recipient’s account is inactive or restricted. Funds have been returned to your account.

section/RECEIVER_ACCOUNT_NOT_ELIGIBLE RECEIVER_ACCOUNT_NOT_ELIGIBLE

Message:

The receiver account is not eligible to receive the payout sent.

section/RECEIVER_ACCOUNT_UNVERIFIED RECEIVER_ACCOUNT_UNVERIFIED

Message:

Your Payout request does not comply with the receiver country regulations. To send this payout, the receiver needs to update and verify their account information.

section/RECEIVER_COUNTRY_NOT_ALLOWED RECEIVER_COUNTRY_NOT_ALLOWED

Message:

We can’t send this payout because the recipient lives in a country where payouts are not allowed.

section/RECEIVER_REFUSED RECEIVER_REFUSED

Message:

The recipient has refused this payout in this currency. Try resending in a different currency.

section/RECEIVER_STATE_RESTRICTED RECEIVER_STATE_RESTRICTED

Message:

We can’t send this payout because the recipient lives in a state where payouts are not allowed.

section/RECEIVER_UNCONFIRMED RECEIVER_UNCONFIRMED

Message:

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.

section/RECEIVER_UNREGISTERED RECEIVER_UNREGISTERED

Message:

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.

section/RECEIVER_YOUTH_ACCOUNT RECEIVER_YOUTH_ACCOUNT

Message:

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.

section/RECEIVING_LIMIT_EXCEEDED RECEIVING_LIMIT_EXCEEDED

Message:

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.

section/REFUSED_ACCESS_DENIED REFUSED_ACCESS_DENIED

Message:

Your account is not allowed to send money. Check with your primary account holder to get permission to send money.

section/REGULATORY_BLOCKED REGULATORY_BLOCKED

Message:

This transaction is blocked due to regulatory compliance restrictions.

section/REGULATORY_PENDING REGULATORY_PENDING

Message:

This transaction is pending, while it is reviewed for compliance with government regulations.

section/REQUIRED_SCOPE_MISSING REQUIRED_SCOPE_MISSING

Message:

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.

section/RISK_DECLINE RISK_DECLINE

Message:

This transaction was declined due to risk concerns.

section/SELF_PAY_NOT_ALLOWED SELF_PAY_NOT_ALLOWED

Message:

You can’t send a payout to yourself. Try sending it to a different account.

section/SENDER_ACCOUNT_LOCKED SENDER_ACCOUNT_LOCKED

Message:

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.

section/SENDER_ACCOUNT_UNVERIFIED SENDER_ACCOUNT_UNVERIFIED

Message:

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.

section/SENDER_STATE_RESTRICTED SENDER_STATE_RESTRICTED

Message:

Your address is in a state where payouts are not allowed. Contact your account manager or our customer service team for assistance.

section/SPENDING_LIMIT_EXCEEDED SPENDING_LIMIT_EXCEEDED

Message:

You’ve exceeded your spending limit. Contact your account manager or our customer service team for assistance.

section/TRANSACTION_DECLINED_BY_TRAVEL_RULE TRANSACTION_DECLINED_BY_TRAVEL_RULE

Message:

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.

section/TRANSACTION_LIMIT_EXCEEDED TRANSACTION_LIMIT_EXCEEDED

Message:

This payout request has exceeded the limit for this type of transaction. The funds have been returned to your account.

section/UNDEFINED UNDEFINED

Message:

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.

section/UNVERIFIED_RECIPIENT_NOT_SUPPORTED UNVERIFIED_RECIPIENT_NOT_SUPPORTED

Message:

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.

section/USER_BUSINESS_ERROR USER_BUSINESS_ERROR

Message:

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.

section/USER_COUNTRY_NOT_ALLOWED USER_COUNTRY_NOT_ALLOWED

Message:

Your address is in a country where payouts are not allowed. Contact your account manager or our customer service team for assistance.

section/USER_FUNDING_SOURCE_INELIGIBLE USER_FUNDING_SOURCE_INELIGIBLE

Message:

The funding source for this payout is not allowed. Try again by using your PayPal balance instead.

section/VALIDATION_ERROR VALIDATION_ERROR

Message:

JSON request is malformed. Check your request format and try again.

section/ZERO_AMOUNT ZERO_AMOUNT

Message:

Please provide a valid payment amount.

tag/Definitions Definitions

schema/alternate_notification_method alternate_notification_method

Captures additional notification modes to reach out to the receiver regarding this payment.


phone	object (Phone) The mobile phone number of the receiver.

Copy

Expand allCollapse all

`{"phone": {"country_code": "str",

"national_number": "string",

"extension_number": "string"

}

schema/application_context application_context

Metadata for Venmo transactions.


social_feed_privacy	string[ 1 .. 15 ] characters^.*$ Default:"PRIVATE" 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.
holler_url	string<uri>[ 1 .. 1000 ] characters Link to a Holler sticker. For Venmo recipients, the sticker displays with the payout message. The maximum URL length is 151.
logo_url	string<uri>[ 0 .. 1000 ] characters 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.

Copy

`{"social_feed_privacy": "PRIVATE",

"holler_url": "http://example.com",

"logo_url": "http://example.com"

schema/batch_enum batch_status

The payouts status.

string (batch_status) [ 1 .. 36 ] characters^[0-9A-Z_]+$

The payouts status.

Enum Value	Description
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.

Copy

"DENIED"

schema/create_payout_request create_payout_request

The create payout request.


items required	Array of objects (payout_item_request) [ 1 .. 15000 ] items An array of individual payout items.
sender_batch_header required	object (sender_batch_header) The sender-provided payout header for a payout request.

Copy

Expand allCollapse all

`{"items": [{"recipient_type": "string",

"note": "string",

"receiver": "string",

"sender_item_id": "string",

"recipient_wallet": "PAYPAL",

"amount": {"currency": "string",

"value": "string"

},

"alternate_notification_method": {"phone": {"country_code": "str",

"national_number": "string",

"extension_number": "string"

}

},

"notification_language": "string",

"application_context": {"social_feed_privacy": "PRIVATE",

"holler_url": "http://example.com",

"logo_url": "http://example.com"

},

"purpose": "AWARDS"

}

],

"sender_batch_header": {"sender_batch_id": "string",

"recipient_type": "string",

"email_subject": "string",

"email_message": "string",

"note": "string"

}

schema/currency Currency

The currency and amount for a financial transaction, such as a balance or payment due.


currency required	string The three-character ISO-4217 currency code.
value required	string 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.

Copy

`{"currency": "string",

"value": "string"

schema/error Error

The error details.


name required	string The human-readable, unique name of the error.
message required	string The message that describes the error.
debug_id required	string 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.
details	Array of objects (Error Details) An array of additional details about the error.
links	Array of objects (Link Description) An array of request-related HATEOAS links.

Copy

Expand allCollapse all

`{"name": "string",

"message": "string",

"debug_id": "string",

"information_link": "string",

"details": [{"field": "string",

"value": "string",

"location": "body",

"issue": "string",

"description": "string"

}

],

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

]

schema/error_details Error Details

The error details. Required for client-side 4XX errors.


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 Default:"body" The location of the field that caused the error. Value is `body`, `path`, or `query`.
issue required	string 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.

Copy

`{"field": "string",

"value": "string",

"location": "body",

"issue": "string",

"description": "string"

schema/funding_source funding_source

Identifies a funding source type.

string (funding_source) [ 1 .. 36 ] characters^[0-9A-Z_]+$

Identifies a funding source type.

Value	Description
BALANCE	Funded by balance.

Copy

"BALANCE"

schema/language language

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.

string<ppaas_common_language_v3> (language) [ 2 .. 10 ] characters^[a-z]{2}(?:-[A-Z][a-z]{3})?(?😦?:[A-Z]{2}))...Show pattern

Copy

"string"

schema/link_description Link Description

The request-related HATEOAS link information.


href required	string 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 required	string The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method	string The HTTP method required to make the related call. Enum:"GET""POST""PUT""DELETE""HEAD""CONNECT""OPTIONS""PATCH"

Copy

`{"href": "string",

"rel": "string",

"method": "GET"

schema/link_description_v4 Link Description

The request-related HATEOAS link information.


href required	string 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 required	string The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method	string The HTTP method required to make the related call. Enum:"GET""POST""PUT""DELETE""HEAD""CONNECT""OPTIONS""PATCH"

Copy

`{"href": "string",

"rel": "string",

"method": "GET"

schema/name Name

The name of the party.


prefix	string<= 140 characters The prefix, or title, to the party's name.
given_name	string<= 140 characters When the party is a person, the party's given, or first, name.
surname	string<= 140 characters 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.
middle_name	string<= 140 characters 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.
suffix	string<= 140 characters The suffix for the party's name.
alternate_full_name	string<= 300 characters 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<= 300 characters When the party is a person, the party's full name.

Copy

`{"prefix": "string",

"given_name": "string",

"surname": "string",

"middle_name": "string",

"suffix": "string",

"alternate_full_name": "string",

"full_name": "string"

schema/patch Patch

The JSON patch object to apply partial updates to resources.

| op
required | string

The operation.

Enum Value	Description
add	Depending on the target location reference, completes one of these functions: - The target location is an array index. Inserts a new value into the array at the specified index. - The target location is an object parameter that does not already exist. Adds a new parameter to the object. - The target location is an object parameter that does exist. Replaces that parameter's value. The `value` parameter defines the value to add. For more information, see 4.1. add.
remove	Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.
replace	Replaces the value at the target location with a new value. The operation object must contain a `value` parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.
move	Removes the value at a specified location and adds it to the target location. The operation object must contain a `from` parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the `from` location must exist. For more information, see 4.4. move.
copy	Copies the value at a specified location to the target location. The operation object must contain a `from` parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the `from` location must exist. For more information, see 4.5. copy.
test	Tests that a value at the target location is equal to a specified value. The operation object must contain a `value` parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the `value` value. For test, `equal` indicates that the value at the target location and the value that `value` defines are of the same JSON type. The data type of the value determines how equality is defined:

Type	Considered equal if both values
strings	Contain the same number of Unicode characters and their code points are byte-by-byte equal.
numbers	Are numerically equal.
arrays	Contain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objects	Contain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (`false`, `true`, and `null`)	Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.

For more information, see 4.6. test. | | | path | string
The JSON Pointer to the target document location at which to complete the operation. | | value | object (Patch Value)
The value to apply. The remove operation does not require a value. | | from | string
The JSON Pointer to the target document location from which to move the value. Required for the move operation. |

Copy

Expand allCollapse all

`{"op": "add",

"path": "string",

"value": { },

"from": "string"

schema/payout payout

The create payout response.


links	Array of objects (Link Description) [ 1 .. 15000 ] items An array of request-related HATEOAS links.
batch_header	object (payout_header) The payout header.

Copy

Expand allCollapse all

`{"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

],

"batch_header": {"payout_batch_id": "string",

"time_created": "2019-08-24T14:15:22Z",

"batch_status": "DENIED",

"sender_batch_header": {"sender_batch_id": "string",

"email_subject": "string",

"email_message": "string",

"recipient_type": "EMAIL"

}

schema/payout_batch payout_batch

The PayPal-generated batch status.


total_items	integer[ 0 .. 15000 ] The total number of items in the full result list.
total_pages	integer[ 0 .. 1000 ] The total number of pages.
items	Array of objects (payout_batch_items) [ 0 .. 15000 ] items An array of individual items.
links	Array of objects (Link Description) [ 0 .. 15000 ] items An array of request-related HATEOAS links.
batch_header	object (payout_batch_header) A payout header. Includes the generated payout status.

Copy

Expand allCollapse all

`{"total_items": 15000,

"total_pages": 1000,

"items": [{"payout_item_id": "string",

"transaction_id": "string",

"activity_id": "string",

"payout_batch_id": "string",

"time_processed": "2019-08-24T14:15:22Z",

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

],

"transaction_status": "SUCCESS",

"payout_item_fee": {"currency": "string",

"value": "string"

},

"payout_item": {"note": "string",

"receiver": "string",

"sender_item_id": "string",

"recipient_type": "EMAIL",

"amount": {"currency": "string",

"value": "string"

},

"recipient_name": {"prefix": "string",

"given_name": "string",

"surname": "string",

"middle_name": "string",

"suffix": "string",

"alternate_full_name": "string",

"full_name": "string"

},

"recipient_wallet": "PAYPAL",

"purpose": "AWARDS"

},

"currency_conversion": {"exchange_rate": "string",

"from_amount": {"currency": "string",

"value": "string"

},

"to_amount": {"currency": "string",

"value": "string"

}

},

"errors": {"name": "string",

"message": "string",

"debug_id": "string",

"information_link": "string",

"details": [{"field": "string",

"value": "string",

"location": "body",

"issue": "string",

"description": "string"

}

],

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

]

}

}

],

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

],

"batch_header": {"payout_batch_id": "string",

"time_created": "2019-08-24T14:15:22Z",

"time_completed": "2019-08-24T14:15:22Z",

"time_closed": "2019-08-24T14:15:22Z",

"batch_status": "DENIED",

"sender_batch_header": {"sender_batch_id": "string",

"email_subject": "string",

"email_message": "string",

"recipient_type": "EMAIL"

"funding_source": "BALANCE",

"amount": {"currency": "string",

"value": "string"

"fees": {"currency": "string",

"value": "string"

}

schema/payout_batch_header payout_batch_header

The payout header that is returned in response to a payout header request. Shows details for an entire payout request.

| payout_batch_id
required | string[ 0 .. 30 ] characters^.*$
The PayPal-generated ID for a payout. | | time_created | string<date-time>[ 0 .. 100 ] characters
The date and time when processing for the payout began, in Internet date and time format. | | time_completed | string<date-time>[ 0 .. 100 ] characters
The date and time when processing for the payout was completed, in Internet date and time format. | | time_closed | string<date-time>[ 0 .. 100 ] characters
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. | | batch_status
required | string (batch_status) [ 1 .. 36 ] characters^[0-9A-Z_]+$

The PayPal-generated payout status. If the payout passes preliminary checks, the status is PENDING.

Enum Value	Description
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.
sender_batch_header required	object (payout_sender_batch_header) The original payout header, as provided by the payment sender.
funding_source	string (funding_source) [ 1 .. 36 ] characters^[0-9A-Z_]+$

The ID to differentiate a PayPal balance-funded transaction from a PayPal treasury-funded transaction.

Value	Description
BALANCE	Funded by balance.
amount	object (Currency) The currency and total amount requested for the payouts.
fees	object (Currency) 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.

Copy

Expand allCollapse all

`{"payout_batch_id": "string",

"time_created": "2019-08-24T14:15:22Z",

"time_completed": "2019-08-24T14:15:22Z",

"time_closed": "2019-08-24T14:15:22Z",

"batch_status": "DENIED",

"sender_batch_header": {"sender_batch_id": "string",

"email_subject": "string",

"email_message": "string",

"recipient_type": "EMAIL"

"funding_source": "BALANCE",

"amount": {"currency": "string",

"value": "string"

"fees": {"currency": "string",

"value": "string"

}

schema/payout_batch_items payout_batch_items

The payout item status and other details.

| payout_item_id
required | string[ 0 .. 30 ] characters^.*$
The ID for the payout item. Viewable when you show details for a payout. | | transaction_id | string[ 0 .. 30 ] characters^.*$
The PayPal-generated ID for the transaction. | | activity_id | string[ 0 .. 30 ] characters^.*$
The unique PayPal-generated common ID created to link sender side and receiver side transaction. Used for tracking. | | payout_batch_id
required | string[ 0 .. 30 ] characters^.*$
The PayPal-generated ID for the payout. | | time_processed | string<date-time>[ 0 .. 100 ] characters
The date and time when this item was last processed, in Internet date and time format. | | links | Array of objects (Link Description) [ 0 .. 15000 ] items
An array of request-related HATEOAS links. | | transaction_status | string (transaction_status) [ 1 .. 36 ] characters^[0-9A-Z_]+$

The item transaction status.

Note: For POST/v1/payments/payouts-item/{payout_item_id}/cancel, the only possible transaction_status value is RETURNED.

Enum Value	Description
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_fee	object (Currency) The fee, in U.S. dollars.
payout_item required	object (payout_item_detail) The sender-provided information for the payout item.
currency_conversion	object (payout_currency_conversion) The currency conversion applicable for this payout item.
errors	object (Error) The error details.

Copy

Expand allCollapse all

`{"payout_item_id": "string",

"transaction_id": "string",

"activity_id": "string",

"payout_batch_id": "string",

"time_processed": "2019-08-24T14:15:22Z",

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

],

"transaction_status": "SUCCESS",

"payout_item_fee": {"currency": "string",

"value": "string"

"payout_item": {"note": "string",

"receiver": "string",

"sender_item_id": "string",

"recipient_type": "EMAIL",

"amount": {"currency": "string",

"value": "string"

"recipient_name": {"prefix": "string",

"given_name": "string",

"surname": "string",

"middle_name": "string",

"suffix": "string",

"alternate_full_name": "string",

"full_name": "string"

"recipient_wallet": "PAYPAL",

"purpose": "AWARDS"

"currency_conversion": {"exchange_rate": "string",

"from_amount": {"currency": "string",

"value": "string"

"to_amount": {"currency": "string",

"value": "string"

}

"errors": {"name": "string",

"message": "string",

"debug_id": "string",

"information_link": "string",

"details": [{"field": "string",

"value": "string",

"location": "body",

"issue": "string",

"description": "string"

}

],

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

]

}

schema/payout_currency_conversion payout_currency_conversion

The currency conversion resource.


exchange_rate	string[ 0 .. 30 ] characters^.*$ The exchange rate that is applied for this payout.
from_amount	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.
to_amount	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.

Copy

Expand allCollapse all

`{"exchange_rate": "string",

"from_amount": {"currency": "string",

"value": "string"

"to_amount": {"currency": "string",

"value": "string"

}

schema/payout_header payout_header

The payout header that is returned in response to a payout header request. Shows details for an entire payout request.

The PayPal-generated payout status. If the payout passes preliminary checks, the status is PENDING.

Enum Value	Description
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.
sender_batch_header required	object (payout_sender_batch_header) The original payout header, as provided by the payment sender.

Copy

Expand allCollapse all

`{"payout_batch_id": "string",

"time_created": "2019-08-24T14:15:22Z",

"batch_status": "DENIED",

"sender_batch_header": {"sender_batch_id": "string",

"email_subject": "string",

"email_message": "string",

"recipient_type": "EMAIL"

}

schema/payout_item_detail payout_item_detail

The details for a sender-created payout to a single recipient.

| note | string[ 0 .. 4000 ] characters^.*$
The sender-specified note for notifications. Supports up to 4000 ASCII characters and 1000 non-ASCII characters. | | receiver
required | string[ 0 .. 127 ] characters^.*$
The receiver of the payment. Corresponds to the recipient_type value in the request. | | sender_item_id | string[ 0 .. 63 ] characters^.*$
A sender-specified ID number. Tracks the payout in an accounting system. | | recipient_type | string (recipient_type) [ 1 .. 36 ] characters^[0-9A-Z_]+$

The ID type that identifies the payment receiver.

Enum Value	Description
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 required	object (Currency) 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.
recipient_name	object (Name) The name of the recipient where money is credited. For `UNCLAIMED` payments, the recipient name is populated after the payment is claimed.
recipient_wallet	string (recipient_wallet) [ 1 .. 36 ] characters^[0-9A-Z_]+$

Default:"PAYPAL"

The recipient wallet.

Enum Value	Description
PAYPAL	PayPal Wallet.
VENMO	Venmo Wallet.
purpose	string (purpose) [ 1 .. 40 ] characters^[A-Z0-9_]+$

The purpose of the transaction.

Enum Value	Description
AWARDS	Awards payouts.
PRIZES	Prizes payouts.
DONATIONS	Donation payouts.
GOODS	Payouts for goods sold.
SERVICES	Payouts for services provided.
REBATES	Rebate payouts.
CASHBACK	Cashback payouts.
DISCOUNTS	Discount payouts.
NON_GOODS_OR_SERVICES	Payouts for any non-goods or services.

Copy

Expand allCollapse all

`{"note": "string",

"receiver": "string",

"sender_item_id": "string",

"recipient_type": "EMAIL",

"amount": {"currency": "string",

"value": "string"

"recipient_name": {"prefix": "string",

"given_name": "string",

"surname": "string",

"middle_name": "string",

"suffix": "string",

"alternate_full_name": "string",

"full_name": "string"

"recipient_wallet": "PAYPAL",

"purpose": "AWARDS"

schema/payout_item_request payout_item_request

The sender-created payout to a recipient.

| recipient_type | string[ 0 .. 13 ] characters^.*$
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 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. | | note | string[ 0 .. 4000 ] characters^.*$
The sender-specified note for notifications. Supports up to 4000 ASCII characters and 1000 non-ASCII characters. | | receiver
required | string[ 0 .. 127 ] characters^.*$
The receiver of the payment. Corresponds to the recipient_type value in the request. Max value of up to 127 single-byte characters. | | sender_item_id | string[ 0 .. 63 ] characters^.*$
The sender-specified ID number. Tracks the payout in an accounting system. | | recipient_wallet | string[ 0 .. 36 ] characters^.*$
Default:"PAYPAL"
The recipient wallet. | | amount
required | object (Currency)
The currency and amount to pay the receiver. | | alternate_notification_method | object (alternate_notification_method)
Captures additional notification modes to reach out to the receiver regarding this payment. | | notification_language | string<ppaas_common_language_v3> (language) [ 2 .. 10 ] characters^[a-z]{2}(?:-[A-Z][a-z]{3})?(?😦?:[A-Z]{2}))...Show pattern
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. | | application_context | object (application_context)
Metadata for accepting additional information from merchants to Venmo. | | purpose | string (purpose) [ 1 .. 40 ] characters^[A-Z0-9_]+$

The purpose of the transaction.

Enum Value	Description
AWARDS	Awards payouts.
PRIZES	Prizes payouts.
DONATIONS	Donation payouts.
GOODS	Payouts for goods sold.
SERVICES	Payouts for services provided.
REBATES	Rebate payouts.
CASHBACK	Cashback payouts.
DISCOUNTS	Discount payouts.
NON_GOODS_OR_SERVICES	Payouts for any non-goods or services.

Copy

Expand allCollapse all

`{"recipient_type": "string",

"note": "string",

"receiver": "string",

"sender_item_id": "string",

"recipient_wallet": "PAYPAL",

"amount": {"currency": "string",

"value": "string"

"alternate_notification_method": {"phone": {"country_code": "str",

"national_number": "string",

"extension_number": "string"

}

"notification_language": "string",

"application_context": {"social_feed_privacy": "PRIVATE",

"holler_url": "http://example.com",

"logo_url": "http://example.com"

"purpose": "AWARDS"

schema/payout_item payout_item_response

The payout item status and other details. 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.

| payout_item_id
required | string[ 0 .. 30 ] characters^.*$
The ID for the payout item. Visible when you show details for a payout. | | transaction_id | string[ 0 .. 30 ] characters^.*$
The PayPal-generated ID for the transaction. | | activity_id | string[ 0 .. 30 ] characters^.*$
The unique PayPal-generated common ID that links the sender- and receiver-side transactions. Used for tracking. | | payout_batch_id
required | string[ 0 .. 30 ] characters^.*$
The PayPal-generated ID for the payout batch. | | sender_batch_id | string[ 0 .. 256 ] characters^.*$
A sender-specified ID. Tracks the payout in an accounting system. Should be unique within 30 days. | | time_processed | string<date-time>[ 1 .. 100 ] characters
The date and time when this item was last processed, in Internet date and time format. | | links | Array of objects (Link Description) [ 0 .. 15000 ] items
An array of request-related HATEOAS links. | | transaction_status | string (transaction_status) [ 1 .. 36 ] characters^[0-9A-Z_]+$

The item transaction status.

Note: For POST/v1/payments/payouts-item/{payout_item_id}/cancel, the only possible transaction_status value is RETURNED.

Enum Value	Description
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_fee	object (Currency) The estimate for the payout fee. Initially, the fee is `0`. The fee is populated after the item moves to the `PENDING` state
payout_item required	object (payout_item_detail) The sender-provided information for the payout item.
currency_conversion	object (payout_currency_conversion) The currency conversion applicable for this payout item.
errors	object (Error) The error details.

Copy

Expand allCollapse all

`{"payout_item_id": "string",

"transaction_id": "string",

"activity_id": "string",

"payout_batch_id": "string",

"sender_batch_id": "string",

"time_processed": "2019-08-24T14:15:22Z",

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

],

"transaction_status": "SUCCESS",

"payout_item_fee": {"currency": "string",

"value": "string"

"payout_item": {"note": "string",

"receiver": "string",

"sender_item_id": "string",

"recipient_type": "EMAIL",

"amount": {"currency": "string",

"value": "string"

"recipient_name": {"prefix": "string",

"given_name": "string",

"surname": "string",

"middle_name": "string",

"suffix": "string",

"alternate_full_name": "string",

"full_name": "string"

"recipient_wallet": "PAYPAL",

"purpose": "AWARDS"

"currency_conversion": {"exchange_rate": "string",

"from_amount": {"currency": "string",

"value": "string"

"to_amount": {"currency": "string",

"value": "string"

}

"errors": {"name": "string",

"message": "string",

"debug_id": "string",

"information_link": "string",

"details": [{"field": "string",

"value": "string",

"location": "body",

"issue": "string",

"description": "string"

}

],

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

]

}

schema/payout_sender_batch_header payout_sender_batch_header

The sender-provided header for a payout request.

| sender_batch_id | string[ 0 .. 256 ] characters^.*$
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. | | email_subject | string[ 0 .. 255 ] characters^.*$
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. | | email_message | string[ 0 .. 1000 ] characters^.*$
The email message that PayPal sends when the payout item completes. The message is the same for all recipients. | | recipient_type | string (recipient_type) [ 1 .. 36 ] characters^[0-9A-Z_]+$

The ID type that identifies the payment receiver.

Enum Value	Description
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.

Copy

`{"sender_batch_id": "string",

"email_subject": "string",

"email_message": "string",

"recipient_type": "EMAIL"

schema/phone Phone

The phone number in its canonical international E.164 numbering plan format.


country_code required	string[ 1 .. 3 ] characters^[0-9]{1,3}?$ 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 required	string[ 1 .. 14 ] characters^[0-9]{1,14}?$ 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[ 1 .. 15 ] characters^[0-9]{1,15}?$ The extension number.

Copy

`{"country_code": "str",

"national_number": "string",

"extension_number": "string"

schema/purpose_enum purpose

The purpose of the transaction.

string (purpose) [ 1 .. 40 ] characters^[A-Z0-9_]+$

The purpose of the transaction.

Enum Value	Description
AWARDS	Awards payouts.
PRIZES	Prizes payouts.
DONATIONS	Donation payouts.
GOODS	Payouts for goods sold.
SERVICES	Payouts for services provided.
REBATES	Rebate payouts.
CASHBACK	Cashback payouts.
DISCOUNTS	Discount payouts.
NON_GOODS_OR_SERVICES	Payouts for any non-goods or services.

Copy

"AWARDS"

schema/recipient_enum recipient_type

The ID type that identifies the payment receiver.

string (recipient_type) [ 1 .. 36 ] characters^[0-9A-Z_]+$

The ID type that identifies the payment receiver.

Enum Value	Description
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.

Copy

"EMAIL"

schema/recipient_wallet_enum recipient_wallet

The wallet where the recipient receives the payout. Payouts to Venmo recipients require a 'note' string and a US mobile phone number.

string (recipient_wallet) [ 1 .. 36 ] characters^[0-9A-Z_]+$

Default:"PAYPAL"

The wallet where the recipient receives the payout. Payouts to Venmo recipients require a 'note' string and a US mobile phone number.

Enum Value	Description
PAYPAL	PayPal Wallet.
VENMO	Venmo Wallet.

Copy

"PAYPAL"

schema/sender_batch_header sender_batch_header

The sender-provided payout header for a payout request.


sender_batch_id	string[ 0 .. 256 ] characters^.$ 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.
recipient_type	string[ 0 .. 13 ] characters^.*$ The ID type that identifies the recipient of the payment. For example, `EMAIL`.
email_subject	string[ 0 .. 255 ] characters^.*$ 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.
email_message	string[ 0 .. 1000 ] characters^.*$ The email message that PayPal sends when the payout item completes. The message is the same for all recipients.
note	string[ 0 .. 1000 ] characters^.*$ The payouts and item-level notes are concatenated in the email. The maximum combined length of the notes is 1000 characters.

Copy

`{"sender_batch_id": "string",

"recipient_type": "string",

"email_subject": "string",

"email_message": "string",

"note": "string"

schema/transaction_enum transaction_status

The item transaction status.

Note: For POST/v1/payments/payouts-item/{payout_item_id}/cancel, the only possible transaction_status value is RETURNED.

string (transaction_status) [ 1 .. 36 ] characters^[0-9A-Z_]+$

The item transaction status.

Note: For POST/v1/payments/payouts-item/{payout_item_id}/cancel, the only possible transaction_status value is RETURNED.

Enum Value	Description
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.

Copy

"SUCCESS"

Payouts(1) ​

operation/payouts.post Create batch payout ​

header Parameters ​

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json ​

operation/payouts.get Show payout batch details ​

path Parameters ​

query Parameters ​

operation/payouts-item.get Show payout item details ​

path Parameters ​

operation/payouts-item.cancel Cancel unclaimed payout item ​

path Parameters ​

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json ​

tag/Errors Errors ​

section/ACCOUNT_RESTRICTED ACCOUNT_RESTRICTED ​

section/ACCOUNT_UNCONFIRMED_EMAIL ACCOUNT_UNCONFIRMED_EMAIL ​

section/APPROVER_DENIED APPROVER_DENIED ​

section/AUTHORIZATION_ERROR AUTHORIZATION_ERROR ​

section/BATCH_NOT_COMPLETED BATCH_NOT_COMPLETED ​

section/CLOSED_MARKET CLOSED_MARKET ​

section/CURRENCY_COMPLIANCE CURRENCY_COMPLIANCE ​

section/CURRENCY_NOT_SUPPORTED_FOR_RECEIVER CURRENCY_NOT_SUPPORTED_FOR_RECEIVER ​

section/DUPLICATE_ITEM DUPLICATE_ITEM ​

section/GAMER_FAILED_COUNTRY_OF_RESIDENCE_CHECK GAMER_FAILED_COUNTRY_OF_RESIDENCE_CHECK ​

section/GAMER_FAILED_FUNDING_SOURCE_CHECK GAMER_FAILED_FUNDING_SOURCE_CHECK ​

section/GAMING_INVALID_PAYMENT_FLOW GAMING_INVALID_PAYMENT_FLOW ​

section/INSUFFICIENT_FUNDS INSUFFICIENT_FUNDS ​

section/INTERNAL_ERROR INTERNAL_ERROR ​

section/INVALID_EMAIL INVALID_EMAIL ​

section/ITEM_ALREADY_CANCELLED ITEM_ALREADY_CANCELLED ​

section/ITEM_CANCELLATION_FAILED ITEM_CANCELLATION_FAILED ​

section/ITEM_INCORRECT_STATUS ITEM_INCORRECT_STATUS ​

section/NEGATIVE_BALANCE NEGATIVE_BALANCE ​

section/NON_HOLDING_CURRENCY NON_HOLDING_CURRENCY ​

section/PENDING_RECIPIENT_NON_HOLDING_CURRENCY_PAYMENT_PREFERENCE PENDING_RECIPIENT_NON_HOLDING_CURRENCY_PAYMENT_PREFERENCE ​

section/PHONE_NUMBER_INVALID PHONE_NUMBER_INVALID ​

section/PHONE_NUMBER_SMS_OPTOUT PHONE_NUMBER_SMS_OPTOUT ​

section/POS_LIMIT_EXCEEDED POS_LIMIT_EXCEEDED ​

section/RATE_LIMIT_VALIDATION_FAILURES RATE_LIMIT_VALIDATION_FAILURES ​

section/RECEIVER_ACCOUNT_LIMITATION RECEIVER_ACCOUNT_LIMITATION ​

section/RECEIVER_ACCOUNT_LOCKED RECEIVER_ACCOUNT_LOCKED ​

section/RECEIVER_ACCOUNT_NOT_ELIGIBLE RECEIVER_ACCOUNT_NOT_ELIGIBLE ​

section/RECEIVER_ACCOUNT_UNVERIFIED RECEIVER_ACCOUNT_UNVERIFIED ​

section/RECEIVER_COUNTRY_NOT_ALLOWED RECEIVER_COUNTRY_NOT_ALLOWED ​

section/RECEIVER_REFUSED RECEIVER_REFUSED ​

section/RECEIVER_STATE_RESTRICTED RECEIVER_STATE_RESTRICTED ​

section/RECEIVER_UNCONFIRMED RECEIVER_UNCONFIRMED ​

section/RECEIVER_UNREGISTERED RECEIVER_UNREGISTERED ​

section/RECEIVER_YOUTH_ACCOUNT RECEIVER_YOUTH_ACCOUNT ​

section/RECEIVING_LIMIT_EXCEEDED RECEIVING_LIMIT_EXCEEDED ​

section/REFUSED_ACCESS_DENIED REFUSED_ACCESS_DENIED ​

section/REGULATORY_BLOCKED REGULATORY_BLOCKED ​

section/REGULATORY_PENDING REGULATORY_PENDING ​

section/REQUIRED_SCOPE_MISSING REQUIRED_SCOPE_MISSING ​

section/RISK_DECLINE RISK_DECLINE ​

section/SELF_PAY_NOT_ALLOWED SELF_PAY_NOT_ALLOWED ​

section/SENDER_ACCOUNT_LOCKED SENDER_ACCOUNT_LOCKED ​

section/SENDER_ACCOUNT_UNVERIFIED SENDER_ACCOUNT_UNVERIFIED ​

section/SENDER_STATE_RESTRICTED SENDER_STATE_RESTRICTED ​

section/SPENDING_LIMIT_EXCEEDED SPENDING_LIMIT_EXCEEDED ​

section/TRANSACTION_DECLINED_BY_TRAVEL_RULE TRANSACTION_DECLINED_BY_TRAVEL_RULE ​

section/TRANSACTION_LIMIT_EXCEEDED TRANSACTION_LIMIT_EXCEEDED ​

section/UNDEFINED UNDEFINED ​

section/UNVERIFIED_RECIPIENT_NOT_SUPPORTED UNVERIFIED_RECIPIENT_NOT_SUPPORTED ​

section/USER_BUSINESS_ERROR USER_BUSINESS_ERROR ​

section/USER_COUNTRY_NOT_ALLOWED USER_COUNTRY_NOT_ALLOWED ​

section/USER_FUNDING_SOURCE_INELIGIBLE USER_FUNDING_SOURCE_INELIGIBLE ​

section/VALIDATION_ERROR VALIDATION_ERROR ​

section/ZERO_AMOUNT ZERO_AMOUNT ​

tag/Definitions Definitions ​

schema/alternate_notification_method alternate_notification_method ​

schema/application_context application_context ​

schema/batch_enum batch_status ​

schema/create_payout_request create_payout_request ​

schema/currency Currency ​

schema/error Error ​

schema/error_details Error Details ​

schema/funding_source funding_source ​

schema/language language ​

schema/link_description Link Description ​

schema/link_description_v4 Link Description ​

Payouts(1)

operation/payouts.post Create batch payout

header Parameters

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

operation/payouts.get Show payout batch details

path Parameters

query Parameters

operation/payouts-item.get Show payout item details

path Parameters

operation/payouts-item.cancel Cancel unclaimed payout item

path Parameters

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

tag/Errors Errors

section/ACCOUNT_RESTRICTED ACCOUNT_RESTRICTED

section/ACCOUNT_UNCONFIRMED_EMAIL ACCOUNT_UNCONFIRMED_EMAIL

section/APPROVER_DENIED APPROVER_DENIED

section/AUTHORIZATION_ERROR AUTHORIZATION_ERROR

section/BATCH_NOT_COMPLETED BATCH_NOT_COMPLETED

section/CLOSED_MARKET CLOSED_MARKET

section/CURRENCY_COMPLIANCE CURRENCY_COMPLIANCE

section/CURRENCY_NOT_SUPPORTED_FOR_RECEIVER CURRENCY_NOT_SUPPORTED_FOR_RECEIVER

section/DUPLICATE_ITEM DUPLICATE_ITEM

section/GAMER_FAILED_COUNTRY_OF_RESIDENCE_CHECK GAMER_FAILED_COUNTRY_OF_RESIDENCE_CHECK

section/GAMER_FAILED_FUNDING_SOURCE_CHECK GAMER_FAILED_FUNDING_SOURCE_CHECK

section/GAMING_INVALID_PAYMENT_FLOW GAMING_INVALID_PAYMENT_FLOW

section/INSUFFICIENT_FUNDS INSUFFICIENT_FUNDS

section/INTERNAL_ERROR INTERNAL_ERROR

section/INVALID_EMAIL INVALID_EMAIL

section/ITEM_ALREADY_CANCELLED ITEM_ALREADY_CANCELLED

section/ITEM_CANCELLATION_FAILED ITEM_CANCELLATION_FAILED

section/ITEM_INCORRECT_STATUS ITEM_INCORRECT_STATUS

section/NEGATIVE_BALANCE NEGATIVE_BALANCE

section/NON_HOLDING_CURRENCY NON_HOLDING_CURRENCY

section/PENDING_RECIPIENT_NON_HOLDING_CURRENCY_PAYMENT_PREFERENCE PENDING_RECIPIENT_NON_HOLDING_CURRENCY_PAYMENT_PREFERENCE

section/PHONE_NUMBER_INVALID PHONE_NUMBER_INVALID

section/PHONE_NUMBER_SMS_OPTOUT PHONE_NUMBER_SMS_OPTOUT

section/POS_LIMIT_EXCEEDED POS_LIMIT_EXCEEDED

section/RATE_LIMIT_VALIDATION_FAILURES RATE_LIMIT_VALIDATION_FAILURES

section/RECEIVER_ACCOUNT_LIMITATION RECEIVER_ACCOUNT_LIMITATION

section/RECEIVER_ACCOUNT_LOCKED RECEIVER_ACCOUNT_LOCKED

section/RECEIVER_ACCOUNT_NOT_ELIGIBLE RECEIVER_ACCOUNT_NOT_ELIGIBLE

section/RECEIVER_ACCOUNT_UNVERIFIED RECEIVER_ACCOUNT_UNVERIFIED

section/RECEIVER_COUNTRY_NOT_ALLOWED RECEIVER_COUNTRY_NOT_ALLOWED

section/RECEIVER_REFUSED RECEIVER_REFUSED

section/RECEIVER_STATE_RESTRICTED RECEIVER_STATE_RESTRICTED

section/RECEIVER_UNCONFIRMED RECEIVER_UNCONFIRMED

section/RECEIVER_UNREGISTERED RECEIVER_UNREGISTERED

section/RECEIVER_YOUTH_ACCOUNT RECEIVER_YOUTH_ACCOUNT

section/RECEIVING_LIMIT_EXCEEDED RECEIVING_LIMIT_EXCEEDED

section/REFUSED_ACCESS_DENIED REFUSED_ACCESS_DENIED

section/REGULATORY_BLOCKED REGULATORY_BLOCKED

section/REGULATORY_PENDING REGULATORY_PENDING

section/REQUIRED_SCOPE_MISSING REQUIRED_SCOPE_MISSING

section/RISK_DECLINE RISK_DECLINE

section/SELF_PAY_NOT_ALLOWED SELF_PAY_NOT_ALLOWED

section/SENDER_ACCOUNT_LOCKED SENDER_ACCOUNT_LOCKED

section/SENDER_ACCOUNT_UNVERIFIED SENDER_ACCOUNT_UNVERIFIED

section/SENDER_STATE_RESTRICTED SENDER_STATE_RESTRICTED

section/SPENDING_LIMIT_EXCEEDED SPENDING_LIMIT_EXCEEDED

section/TRANSACTION_DECLINED_BY_TRAVEL_RULE TRANSACTION_DECLINED_BY_TRAVEL_RULE

section/TRANSACTION_LIMIT_EXCEEDED TRANSACTION_LIMIT_EXCEEDED

section/UNDEFINED UNDEFINED

section/UNVERIFIED_RECIPIENT_NOT_SUPPORTED UNVERIFIED_RECIPIENT_NOT_SUPPORTED

section/USER_BUSINESS_ERROR USER_BUSINESS_ERROR

section/USER_COUNTRY_NOT_ALLOWED USER_COUNTRY_NOT_ALLOWED

section/USER_FUNDING_SOURCE_INELIGIBLE USER_FUNDING_SOURCE_INELIGIBLE

section/VALIDATION_ERROR VALIDATION_ERROR

section/ZERO_AMOUNT ZERO_AMOUNT

tag/Definitions Definitions

schema/alternate_notification_method alternate_notification_method

schema/application_context application_context

schema/batch_enum batch_status

schema/create_payout_request create_payout_request

schema/currency Currency

schema/error Error

schema/error_details Error Details

schema/funding_source funding_source

schema/language language

schema/link_description Link Description

schema/link_description_v4 Link Description