Skip to main content

Create batch payout

POST 
/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.

Request​

Header Parameters

    PayPal-Request-Id string

    Possible values: non-empty and <= 1000 characters, Value must match regular expression ^.*$

    The server stores keys for 30 days.

Body

    items

    object[]

    required

    An array of individual payout items.

    Possible values: >= 1, <= 15000

  • Array [

    • recipient_type string

    The recipient type. Value is:

    • EMAIL. The unencrypted email. Value is a string of up to 127 single-byte characters.

    • PHONE. The unencrypted phone number.

      Note: The PayPal sandbox does not support the PHONE recipient type.

    • PAYPAL_ID. The encrypted PayPal account number.

    • USER_HANDLE. User handle (or) Username associated with Venmo account.


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

    Possible values: <= 13 characters, Value must match regular expression ^.*$

    note string

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

    Possible values: <= 4000 characters, Value must match regular expression ^.*$

    receiver stringrequired

    The receiver of the payment. Corresponds to the recipient_type value in the request. Max value of up to 127 single-byte characters.

    Possible values: <= 127 characters, Value must match regular expression ^.*$

    sender_item_id string

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

    Possible values: <= 63 characters, Value must match regular expression ^.*$

    recipient_wallet string

    The recipient wallet.

    Possible values: <= 36 characters, Value must match regular expression ^.*$

    Default value: PAYPAL

    amount

    object

    required

    The currency and amount to pay the receiver.

    currency stringrequired
    value stringrequired

    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.

    alternate_notification_method

    object

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

    phone

    object

    The mobile phone number of the receiver.

    country_code stringrequired

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

    Possible values: non-empty and <= 3 characters, Value must match regular expression ^[0-9]{1,3}?$

    national_number stringrequired

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

    Possible values: non-empty and <= 14 characters, Value must match regular expression ^[0-9]{1,14}?$

    extension_number string

    The extension number.

    Possible values: non-empty and <= 15 characters, Value must match regular expression ^[0-9]{1,15}?$

    notification_language ppaas_common_language_v3

    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.

    Possible values: >= 2 characters and <= 10 characters, Value must match regular expression ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$

    application_context

    object

    Metadata for accepting additional information from merchants to Venmo.

    social_feed_privacy string

    This attribute controls the privacy of a payout transaction in recipient’s feed. PUBLIC, FRIENDS_ONLY & PRIVATE are the values that can be used. PUBLIC - The payment displays on the recipient's public Venmo feed. FRIENDS_ONLY - The payment displays only to the recipient's Venmo friends. PRIVATE - The payment displays only on the recipient's personal feed. Defaults to PRIVATE if left blank.

    Possible values: non-empty and <= 15 characters, Value must match regular expression ^.*$

    Default value: PRIVATE
    holler_url uri

    Link to a Holler sticker. For Venmo recipients, the sticker displays with the payout message. The maximum URL length is 151.

    Possible values: non-empty and <= 1000 characters

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

    Possible values: <= 1000 characters

    purpose Purpose (string)

    The purpose of the transaction.

    Possible values: non-empty and <= 40 characters, Value must match regular expression ^[A-Z0-9_]+$, [AWARDS, PRIZES, DONATIONS, GOODS, SERVICES, REBATES, CASHBACK, DISCOUNTS, NON_GOODS_OR_SERVICES]

  • ]

    • sender_batch_header

    object

    required

    The sender-provided payout header for a payout request.

    sender_batch_id string

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

    Note:

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

    If you receive an HTTP 5nn status code, you can safely retry the request with the same sender_batch_id. The API completes a payment only once for a sender_batch_id that is used within 30 days.

    Possible values: <= 256 characters, Value must match regular expression ^.*$

    recipient_type string

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

    Possible values: <= 13 characters, Value must match regular expression ^.*$

    email_subject string

    The subject line for the email that PayPal sends when payment for a payout item completes. The subject line is the same for all recipients. Value is an alphanumeric string of up to 255 single-byte characters.

    Possible values: <= 255 characters, Value must match regular expression ^.*$

    email_message string

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

    Possible values: <= 1000 characters, Value must match regular expression ^.*$

    note string

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

    Possible values: <= 1000 characters, Value must match regular expression ^.*$

Responses​

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.

Schema

    links object[]

    An array of request-related HATEOAS links.

    Possible values: >= 1, <= 15000

    batch_header

    object

    The payout header.

    payout_batch_id stringrequired

    The PayPal-generated ID for a payout.

    Possible values: <= 30 characters, Value must match regular expression ^.*$

    time_created date-time

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

    Possible values: <= 100 characters

    batch_status Batch status (string)required

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

    Possible values: non-empty and <= 36 characters, Value must match regular expression ^[0-9A-Z_]+$, [DENIED, PENDING, PROCESSING, SUCCESS, CANCELED]

    sender_batch_header

    object

    required

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

    sender_batch_id string

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

    Note:

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

    If you receive an HTTP 5nn status code, you can safely retry the request with the same sender_batch_id. The API completes a payment only once for a sender_batch_id that is used within 30 days.

    Possible values: <= 256 characters, Value must match regular expression ^.*$

    email_subject string

    The subject line for the email that PayPal sends when payment for a payout item completes. The subject line is the same for all recipients. Value is an alphanumeric string with a maximum length of 255 single-byte characters.

    Possible values: <= 255 characters, Value must match regular expression ^.*$

    email_message string

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

    Possible values: <= 1000 characters, Value must match regular expression ^.*$

    recipient_type Recipient type (string)

    The ID type that identifies the payment receiver.

    Possible values: non-empty and <= 36 characters, Value must match regular expression ^[0-9A-Z_]+$, [EMAIL, PHONE, PAYPAL_ID]

Loading...