Payouts (1)

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

Create batch payout

post/v1/payments/payouts

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

Notes:

  • PayPal does not process duplicate payouts. If you specify a sender_batch_id that was used in the last 30 days, the API rejects the request with an error message that shows the duplicate sender_batch_id and includes a HATEOAS link to the original payout with the same sender_batch_id.

    If you receive an HTTP 5nn status code, you can safely retry the request with the same sender_batch_id.

  • The Payouts API does not support build notation (BN) codes. In a future Payouts release, you can optionally provide BN codes in the PayPal-Partner-Attribution-Id request header.

    For information about the PayPal-Partner-Attribution-Id header, see HTTP request headers. To learn about or request a BN code, contact your partner manager or see PayPal Partner Program.

SecurityOauth2
Request
header Parameters
PayPal-Request-Id
string

The server stores keys for 30 days.

Request Body schema: application/json
required
Array of objects (payout_item) [ 1 .. 15000 ] characters

An array of individual payout items.

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
application/json
{
  • "items": [
    • {
      • "receiver": "receiver@example.com",
      • "amount": {
        • "currency": "USD",
        • "value": "9.87"
        },
      • "recipient_type": "EMAIL",
      • "note": "Thanks for your patronage!",
      • "sender_item_id": "201403140001",
      • "recipient_wallet": "RECIPIENT_SELECTED"
      }
    ],
  • "sender_batch_header": {
    • "sender_batch_id": "Payouts_2020_100007",
    • "email_subject": "You have a payout!",
    • "email_message": "You have received a payout! Thanks for using our service!"
    }
}
Response samples
application/json
{
  • "batch_header": {
    • "sender_batch_header": {
      • "sender_batch_id": "Payouts_2020_100007",
      • "email_subject": "You have a payout!",
      • "email_message": "You have received a payout! Thanks for using our service!"
      },
    • "payout_batch_id": "5UXD2E8A7EBQJ",
    • "batch_status": "PENDING"
    }
}

Show payout batch details

get/v1/payments/payouts/{payout_batch_id}

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

SecurityOauth2
Request
path Parameters
payout_batch_id
required
string

The ID of the payout for which to show details.

query Parameters
fields
string

Shows details for only the specified fields.

page
integer
Default: 1

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
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 -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
{
  • "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": []
      },
    • {
      • "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": []
      },
    • {
      • "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": []
      },
    • {
      • "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": []
      },
    • {
      • "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": []
      }
    ],
  • "links": []
}

Show payout item details

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

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

SecurityOauth2
Request
path Parameters
payout_item_id
required
string

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 -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
{
  • "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": []
}

Cancel unclaimed payout item

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

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

SecurityOauth2
Request
path Parameters
payout_item_id
required
string

The ID of the payout item to cancel.

Responses
200

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

Request samples 
curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/payouts-item/5KUDKLF8SDC7S/cancel \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer A101.OLQiCmqOpVwigKQQDu3CYlamZ1KTKQmhrbAZK85RIy4IiWh9d_up_lTkhf_lfXdV.P3gvkY3PO28akjKYaDorm12QdfK'
Response samples
application/json
{}

Errors

ACCOUNT_RESTRICTED

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

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.

APPROVER_DENIED

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

AUTHORIZATION_ERROR

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

BATCH_NOT_COMPLETED

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

CLOSED_MARKET

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

CURRENCY_COMPLIANCE

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

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.

DUPLICATE_ITEM

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

GAMER_FAILED_COUNTRY_OF_RESIDENCE_CHECK

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

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.

GAMING_INVALID_PAYMENT_FLOW

Message:
This payment flow is not allowed for gaming merchant accounts.

INSUFFICIENT_FUNDS

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

INTERNAL_ERROR

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

INVALID_EMAIL

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

ITEM_ALREADY_CANCELLED

Message:
This payout request has already been cancelled.

ITEM_CANCELLATION_FAILED

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

ITEM_INCORRECT_STATUS

Message:
You can only cancel items that are unclaimed.

NEGATIVE_BALANCE

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

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.

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.

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.

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.

POS_LIMIT_EXCEEDED

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

RATE_LIMIT_VALIDATION_FAILURES

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

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.

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.

RECEIVER_COUNTRY_NOT_ALLOWED

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

RECEIVER_REFUSED

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

RECEIVER_STATE_RESTRICTED

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

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.

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.

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.

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.

REFUSED_ACCESS_DENIED

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

REGULATORY_BLOCKED

Message:
This transaction is blocked due to regulatory compliance restrictions.

REGULATORY_PENDING

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

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.

RISK_DECLINE

Message:
This transaction was declined due to risk concerns.

SELF_PAY_NOT_ALLOWED

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

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.

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.

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.

SPENDING_LIMIT_EXCEEDED

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

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.

TRANSACTION_LIMIT_EXCEEDED

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

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.

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.

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.

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.

USER_FUNDING_SOURCE_INELIGIBLE

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

VALIDATION_ERROR

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

ZERO_AMOUNT

Message:
Please provide a valid payment amount.

Definitions

alternate_notification_method

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

object (Phone)

The mobile phone number of the receiver.

{
  • "phone": {
    • "country_code": "str",
    • "national_number": "string",
    • "extension_number": "string"
    }
}

application_context

Metadata for Venmo transactions.

social_feed_privacy
string <= 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>

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>

Link to a logo that displays as the sender's profile image in the recipient's Venmo feed. Used to add or update the business profile image. Max image size: 1024 x 1024 pixels. The image should be square and maximum URL length is 2000.

{}

batch_status

The payouts status.

string (batch_status)

The payouts status.

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

"DENIED"

common_components-v3-schema-json-openapi-2.0-language.json

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> (common_components-v3-schema-json-openapi-2.0-language.json) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))...

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"

create_payout_request

The create payout request.

required
Array of objects (payout_item) [ 1 .. 15000 ] characters

An array of individual payout items.

required
object (sender_batch_header)

The sender-provided payout header for a payout request.

{
  • "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": {}
      }
    ],
  • "sender_batch_header": {
    • "sender_batch_id": "string",
    • "recipient_type": "string",
    • "email_subject": "string",
    • "email_message": "string",
    • "note": "string"
    }
}

Currency

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

currency
required
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.

{
  • "currency": "string",
  • "value": "string"
}

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.

Array of objects (Error Details)

An array of additional details about the error.

Array of objects (Link Description)

An array of request-related HATEOAS links.

{
  • "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"
      }
    ]
}

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.

{
  • "field": "string",
  • "value": "string",
  • "location": "body",
  • "issue": "string",
  • "description": "string"
}

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 reason for the error.

{
  • "field": "string",
  • "value": "string",
  • "location": "body",
  • "issue": "string"
}

funding_source

Identifies a funding source type.

string (funding_source)

Identifies a funding source type.

Value: Description
BALANCE

Funded by balance.

"BALANCE"

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.

{
  • "prefix": "string",
  • "given_name": "string",
  • "surname": "string",
  • "middle_name": "string",
  • "suffix": "string",
  • "alternate_full_name": "string",
  • "full_name": "string"
}

payout

The create payout response.

Array of objects (Link Description)

An array of request-related HATEOAS links.

object (payout_header)

The payout header.

{
  • "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"
      }
    }
}

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.

Array of objects (payout_batch_items)

An array of individual items.

Array of objects (Link Description)

An array of request-related HATEOAS links.

object (payout_batch_header)

A payout header. Includes the generated payout status.

{
  • "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"
        },
      • "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"
      }
    }
}

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 <= 30 characters

The PayPal-generated ID for a payout.

time_created
string <date-time>

The date and time when processing for the payout began, in Internet date and time format.

time_completed
string <date-time>

The date and time when processing for the payout was completed, in Internet date and time format.

time_closed
string <date-time>

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)

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

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

required
object (payout_sender_batch_header)

The original payout header, as provided by the payment sender.

funding_source
string (funding_source)

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

Value: Description
BALANCE

Funded by balance.

object (Currency)

The currency and total amount requested for the payouts.

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.

{
  • "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"
    }
}

payout_batch_items

The payout item status and other details.

payout_item_id
required
string <= 30 characters

The ID for the payout item. Viewable when you show details for a payout.

transaction_id
string <= 30 characters

The PayPal-generated ID for the transaction.

activity_id
string <= 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 <= 30 characters

The PayPal-generated ID for the payout.

time_processed
string <date-time>

The date and time when this item was last processed, in Internet date and time format.

Array of objects (Link Description)

An array of request-related HATEOAS links.

transaction_status
string (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.

Enum: 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

The recipient has not claimed this payout, so the funds have been returned to your account.

ONHOLD

This payout request is being reviewed and is on hold.

BLOCKED

This payout request has been blocked.

REFUNDED

This payout request was refunded.

REVERSED

This payout request was reversed.

object (Currency)

The fee, in U.S. dollars.

required
object (payout_item_detail)

The sender-provided information for the payout item.

object (payout_currency_conversion)

The currency conversion applicable for this payout item.

object (Error)

The error details.

{
  • "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"
    },
  • "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"
        }
      ]
    }
}

payout_currency_conversion

The currency conversion resource.

exchange_rate
string

The exchange rate that is applied for this payout.

object (Currency)

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

object (Currency)

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

{
  • "exchange_rate": "string",
  • "from_amount": {
    • "currency": "string",
    • "value": "string"
    },
  • "to_amount": {
    • "currency": "string",
    • "value": "string"
    }
}

payout_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 <= 30 characters

The PayPal-generated ID for a payout.

time_created
string <date-time>

The date and time when processing for the payout began, in Internet date and time format.

batch_status
required
string (batch_status)

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

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

required
object (payout_sender_batch_header)

The original payout header, as provided by the payment sender.

{
  • "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"
    }
}

payout_item

The sender-created payout to a recipient.

recipient_type
string <= 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.


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 <= 4000 characters

The sender-specified note for notifications. Supports up to 4000 ASCII characters and 1000 non-ASCII characters.

receiver
required
string <= 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 <= 63 characters

The sender-specified ID number. Tracks the payout in an accounting system.

recipient_wallet
string <= 36 characters
Default: "PAYPAL"

The recipient wallet.

required
object (Currency)

The currency and amount to pay the receiver.

object (alternate_notification_method)

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

notification_language
string <ppaas_common_language_v3> (common_components-v3-schema-json-openapi-2.0-language.json) [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))...

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.

object (application_context)

Metadata for accepting additional information from merchants to Venmo.

{
  • "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": {}
}

payout_item

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 <= 30 characters

The ID for the payout item. Visible when you show details for a payout.

transaction_id
string <= 30 characters

The PayPal-generated ID for the transaction.

activity_id
string <= 30 characters

The unique PayPal-generated common ID that links the sender- and receiver-side transactions. Used for tracking.

payout_batch_id
required
string <= 30 characters

The PayPal-generated ID for the payout batch.

sender_batch_id
string <= 256 characters

A sender-specified ID. Tracks the payout in an accounting system. Should be unique within 30 days.

time_processed
string <date-time>

The date and time when this item was last processed, in Internet date and time format.

Array of objects (Link Description)

An array of request-related HATEOAS links.

transaction_status
string (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.

Enum: 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

The recipient has not claimed this payout, so the funds have been returned to your account.

ONHOLD

This payout request is being reviewed and is on hold.

BLOCKED

This payout request has been blocked.

REFUNDED

This payout request was refunded.

REVERSED

This payout request was reversed.

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

required
object (payout_item_detail)

The sender-provided information for the payout item.

object (payout_currency_conversion)

The currency conversion applicable for this payout item.

object (Error)

The error details.

{
  • "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"
    },
  • "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"
        }
      ]
    }
}

payout_item_detail

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

note
string <= 4000 characters

The sender-specified note for notifications. Supports up to 4000 ASCII characters and 1000 non-ASCII characters.

receiver
required
string <= 127 characters

The receiver of the payment. Corresponds to the recipient_type value in the request.

sender_item_id
string <= 63 characters

A sender-specified ID number. Tracks the payout in an accounting system.

recipient_type
string (recipient_type)

The ID type that identifies the payment receiver.

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

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.

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)
Default: "PAYPAL"

The recipient wallet.

Enum: Description
PAYPAL

PayPal Wallet.

VENMO

Venmo Wallet.

RECIPIENT_SELECTED

Recipient selects how to receive payment from payment options.

{
  • "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"
}

payout_sender_batch_header

The sender-provided header for a payout request.

sender_batch_id
string <= 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 <= 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 <= 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)

The ID type that identifies the payment receiver.

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

{
  • "sender_batch_id": "string",
  • "email_subject": "string",
  • "email_message": "string",
  • "recipient_type": "EMAIL"
}

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.

{
  • "country_code": "str",
  • "national_number": "string",
  • "extension_number": "string"
}

recipient_type

The ID type that identifies the payment receiver.

string (recipient_type)

The ID type that identifies the payment receiver.

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

"EMAIL"

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)
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: Description
PAYPAL

PayPal Wallet.

VENMO

Venmo Wallet.

RECIPIENT_SELECTED

Recipient selects how to receive payment from payment options.

"PAYPAL"

sender_batch_header

The sender-provided payout header for a payout request.

sender_batch_id
string <= 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 <= 13 characters

The ID type that identifies the recipient of the payment. For example, EMAIL.

email_subject
string <= 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 <= 1000 characters

The email message that PayPal sends when the payout item completes. The message is the same for all recipients.

note
string <= 1000 characters

The payouts and item-level notes are concatenated in the email. The maximum combined length of the notes is 1000 characters.

{
  • "sender_batch_id": "string",
  • "recipient_type": "string",
  • "email_subject": "string",
  • "email_message": "string",
  • "note": "string"
}

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)

The item transaction status.

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

Enum: 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

The recipient has not claimed this payout, so the funds have been returned to your account.

ONHOLD

This payout request is being reviewed and is on hold.

BLOCKED

This payout request has been blocked.

REFUNDED

This payout request was refunded.

REVERSED

This payout request was reversed.

"SUCCESS"