Payouts API

Use the Payouts API to make PayPal payments to multiple PayPal accounts in a single API call. The Payouts API is a fast, convenient way to send commissions, rebates, rewards, and general disbursements. Payouts appear as Mass Payments in the sender's PayPal account as Mass Payment reports. The Payouts API uses the ISO 8601 Internet date and time format.

Payouts (resource group)

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

Create payout

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

Header parameters

For more information about HTTP request headers, see HTTP request headers.
  • PayPal-Request-Id

    string

    The server stores keys for 30 days. For more information about PayPal-Request-Id, see PayPal-Request-Id.

Request body

  • sender_batch_header

    object

    required

    The sender-provided payout header for a payout request.
  • items

    array (contains the payout_item object)

    required

    An array of individual payout items.

    Minimum length: 1.

    Maximum length: 15000.

Sample Request

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/payouts \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "sender_batch_header": {
    "sender_batch_id": "Payouts_2018_100007",
    "email_subject": "You have a payout!",
    "email_message": "You have received a payout! Thanks for using our service!"
  },
  "items": [
    {
      "recipient_type": "EMAIL",
      "amount": {
        "value": "9.87",
        "currency": "USD"
      },
      "note": "Thanks for your patronage!",
      "sender_item_id": "201403140001",
      "receiver": "receiver@example.com"
    },
    {
      "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": "PAYER_ID",
      "amount": {
        "value": "5.32",
        "currency": "USD"
      },
      "note": "Thanks for your patronage!",
      "sender_item_id": "201403140003",
      "receiver": "G83JXTJ5EHCQ2"
    }
  ]
}'

Response

A successful request returns the HTTP 201 Created status code and a JSON response body that show the ID for the payout and payout details. To show payout status, use the payout_batch_id value that appears 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.

Sample Response

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

Show payout batch details

GET /v1/payments/payouts/{payout_batch_id}
Shows the latest status of a payout along with the transaction status and other data for individual items.

Path parameters

  • payout_batch_id

    string

    required

    The ID of the payout for which to show details.

Query parameters

  • fields

    string

    Shows details for only the specified fields.
  • page

    integer

    A non-zero integer representing the page of the results.

    Default: 1.

  • 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 size is 500.
  • total_required

    boolean

    Indicates whether to show the total items and total pages count in the response.

Sample Request

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

Response

A successful request returns the HTTP 200 OK status code.
  • total_items

    integer

    The total number of items in the full result list.
  • total_pages

    integer

    The total number of pages.
  • batch_header

    object

    A payout header. Includes the generated payout status.
  • items

    array (contains the payout_batch_items object)

    An array of individual items.
  • errors

    object

    The error details.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

Sample Response

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

Payouts item (resource group)

Use the /payouts-item resource to show payout item details.

Show payout item details

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

Path parameters

  • payout_item_id

    string

    required

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

Sample Request

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

Response

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

    string

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

    Maximum length: 30.

  • transaction_id

    string

    The PayPal-generated ID for the transaction.

    Maximum length: 30.

  • activity_id

    string

    The PayPal-generated activity ID for the transaction.

    Maximum length: 30.

  • transaction_status

    enum

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

    object

    The estimate for the applicable payout fee. Initially, the fee is 0. The fee is populated after the item moves to the PENDING state
  • payout_batch_id

    string

    The PayPal-generated ID for the payout batch.

    Maximum length: 30.

  • sender_batch_id

    string

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

    Maximum length: 256.

  • payout_item

    object

    The sender-provided information for the payout item.
  • time_processed

    string

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

    object

    The error details.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

Sample Response

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

Cancel unclaimed payment

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

Path parameters

  • payout_item_id

    string

    required

    The ID of the payout item to cancel.

Sample Request

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

Response

A successful request returns the HTTP 200 OK status code.
  • payout_item_id

    string

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

    Maximum length: 30.

  • transaction_id

    string

    The PayPal-generated ID for the transaction.

    Maximum length: 30.

  • activity_id

    string

    The PayPal-generated activity ID for the transaction.

    Maximum length: 30.

  • transaction_status

    enum

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

    object

    The estimate for the applicable payout fee. Initially, the fee is 0. The fee is populated after the item moves to the PENDING state
  • payout_batch_id

    string

    The PayPal-generated ID for the payout batch.

    Maximum length: 30.

  • sender_batch_id

    string

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

    Maximum length: 256.

  • payout_item

    object

    The sender-provided information for the payout item.
  • time_processed

    string

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

    object

    The error details.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

Sample Response

{
  "payout_item_id": "5KUDKLF8SDC7S",
  "transaction_id": "1DG93452WK758815H",
  "activity_id": "0E158638XS0329101",
  "transaction_status": "RETURNED",
  "payout_item_fee": {
    "currency": "USD",
    "value": "0.35"
  },
  "payout_batch_id": "CQMWKDQF5GFLL",
  "sender_batch_id": "Payouts_2018_100006",
  "payout_item": {
    "recipient_type": "EMAIL",
    "amount": {
      "value": "9.87",
      "currency": "USD"
    },
    "note": "Thanks for your patronage!",
    "receiver": "receiver@example.com",
    "sender_item_id": "14Feb_234"
  },
  "time_processed": "2018-01-27T10:17:41Z",
  "errors": {
    "name": "RECEIVER_UNREGISTERED",
    "message": "Receiver is unregistered",
    "information_link": "https://developer.paypal.com/docs/api/payments.payouts-batch#errors"
  },
  "links": [
    {
      "rel": "self",
      "href": "https://api.sandbox.paypal.com/v1/payments/payouts-item/5KUDKLF8SDC7S",
      "method": "GET"
    },
    {
      "rel": "batch",
      "href": "https://api.sandbox.paypal.com/v1/payments/payouts/CQMWKDQF5GFLL",
      "method": "GET"
    }
  ]
}

Common object definitions

batch_header

  • payout_batch_id

    string

    required

    The PayPal-generated ID for a payout.

    Maximum length: 30.

  • batch_status

    enum

    required

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

    string

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

    string

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

    string

    The date and time when the payout was closed, in Internet date and time format.
  • sender_batch_header

    object

    required

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

    enum

    The funding source of the payout sender. The possible values are:
    • BALANCE. Funded by balance.
    • PAYPAL_TREASURY. Funded by special receivable account.
    • VENMO. Funded by special receivable account.
  • amount

    object

    The total amount, in U.S. dollars, requested for the payouts.
  • fees

    object

    The currency and amount of the total estimate for the applicable payouts fees. Initially, the fee is 0. The fee is populated after the payout moves to the PROCESSING state.
  • errors

    object

    The error information.

batch_header_response

  • payout_batch_id

    string

    required

    The PayPal-generated ID for a payout.

    Maximum length: 30.

  • batch_status

    enum

    required

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

    string

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

    object

    required

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

    object

    The error information.

batch_status

  • batch_status

    enum

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

create_payout_request

  • sender_batch_header

    object

    required

    The sender-provided payout header for a payout request.
  • items

    array (contains the payout_item object)

    required

    An array of individual payout items.

    Minimum length: 1.

    Maximum length: 15000.

currency

  • currency

    string

    required

  • value

    string

    required

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

error

  • name

    string

    required

    The human-readable, unique name of the error.

    Read only.

  • debug_id

    string

    The PayPal internal ID. Used for correlation purposes.

    Read only.

  • message

    string

    required

    The message that describes the error.

    Read only.

  • information_link

    string

    required

    The URI to detailed information related to this error for the developer.

    Read only.

  • details

    array (contains the error_details object)

    An array of additional details for the error.

    Read only.

error_details

  • field

    string

    required

    The name of the field that caused the error.
  • issue

    string

    required

    The reason for the error.

errors

  • name

    string

    required

    The human-readable and unique name of the error.

    Read only.

  • debug_id

    string

    The PayPal internal ID, which is used for correlation purposes.

    Read only.

  • message

    string

    required

    The message that describes the error.

    Read only.

  • information_link

    string

    required

    The URI for detailed information related to this error for the developer.

    Read only.

  • payout_error_details

    array (contains the payout_error_detail object)

    An array of additional error details.

    Read only.

funding_source

  • funding_source

    enum

    This enum type identifies the funding type of the payment. Value is:
    • BALANCE. Funded by balance.
    • PAYPAL_TREASURY. Funded by special receivable account.
    The possible values are:
    • BALANCE. Funded by balance.
    • PAYPAL_TREASURY. Funded by special receivable account.
    • VENMO. Funded by special receivable account.

name

  • prefix

    string

    The prefix, or title, to the party's name.

    Maximum length: 140.

  • given_name

    string

    When the party is a person, the party's given, or first, name.

    Maximum length: 140.

  • surname

    string

    When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname.

    Maximum length: 140.

  • middle_name

    string

    When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.

    Maximum length: 140.

  • suffix

    string

    The suffix for the party's name.

    Maximum length: 140.

  • alternate_full_name

    string

    DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.

    Maximum length: 300.

  • full_name

    string

    When the party is a person, the party's full name.

    Maximum length: 300.

name_validation

  • name_validation

payout

payout_batch

  • total_items

    integer

    The total number of items in the full result list.
  • total_pages

    integer

    The total number of pages.
  • batch_header

    object

    A payout header. Includes the generated payout status.
  • items

    array (contains the payout_batch_items object)

    An array of individual items.
  • errors

    object

    The error details.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

payout_batch_items

  • payout_item_id

    string

    required

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

    Maximum length: 30.

  • transaction_id

    string

    The PayPal-generated ID for the transaction.

    Maximum length: 30.

  • activity_id

    string

    The PayPal-generated activity ID for the transaction.

    Maximum length: 30.

  • transaction_status

    enum

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

    object

    The fee, in U.S. dollars.
  • payout_batch_id

    string

    required

    The PayPal-generated ID for the payout.

    Maximum length: 30.

  • payout_item

    object

    required

    The sender-provided information for the payout item.
  • time_processed

    string

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

    object

    The error information.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

payout_error_detail

  • field

    string

    required

    The name of the field that caused the error.
  • issue

    string

    required

    The reason for the error.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

payout_item

  • recipient_type

    string

    The recipient type. Value is:
    • EMAIL. The unencrypted email. Value is a string of up to 127 single-byte characters.
    • PHONE. The unencrypted phone number.
      Note: The PayPal sandbox does not support the PHONE recipient type.
    • PAYPAL_ID. The encrypted PayPal account number.

    If the sender_batch_header includes the recipient_type attribute, payout items use the recipient_type of the sender_batch_header, unless a payout item has its own recipient_type attribute. If the sender_batch_header omits the recipient_type attribute, each payout item must include its own recipient_type value.

    Maximum length: 13.

  • amount

    object

    required

    The currency and amount to pay the receiver.
  • note

    string

    A sender-specified note for notifications.

    Maximum length: 4000.

  • receiver

    string

    required

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

    Maximum length: 127.

  • sender_item_id

    string

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

    Maximum length: 63.

payout_item_detail

  • recipient_type

    enum

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

    object

    required

    The currency and amount of payout item. Might be an integer for currencies like JPY that are not typically fractional or a decimal fraction for currencies like TND that are subdivided into thousandths. For the required number of decimal places for a currency code, see Currency codes - ISO 4217.
  • note

    string

    A sender-specified note for notifications.

    Maximum length: 4000.

  • receiver

    string

    required

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

    Maximum length: 127.

  • sender_item_id

    string

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

    Maximum length: 30.

  • recipient_name

    object

    The name of the recipient of the payment. For UNCLAIMED payments, the recipient name is populated after the payment is claimed.

payout_item_response

  • payout_item_id

    string

    required

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

    Maximum length: 30.

  • transaction_id

    string

    The PayPal-generated ID for the transaction.

    Maximum length: 30.

  • activity_id

    string

    The PayPal-generated activity ID for the transaction.

    Maximum length: 30.

  • transaction_status

    enum

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

    object

    The estimate for the applicable payout fee. Initially, the fee is 0. The fee is populated after the item moves to the PENDING state
  • payout_batch_id

    string

    required

    The PayPal-generated ID for the payout batch.

    Maximum length: 30.

  • sender_batch_id

    string

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

    Maximum length: 256.

  • payout_item

    object

    required

    The sender-provided information for the payout item.
  • time_processed

    string

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

    object

    The error details.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

recipient_type

  • recipient_type

    enum

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

sender_batch_header

  • sender_batch_id

    string

    A sender-specified ID number. Tracks the payout in an accounting system.
    Note: PayPal does not process duplicate payouts. If you specify a sender_batch_id that was used in the last 30 days, the API rejects the request with an error message that shows the duplicate sender_batch_id and includes a HATEOAS link to the original payout with the same sender_batch_id.
    If you receive an HTTP 5nn status code, you can safely retry the request with the same sender_batch_id. The API completes a payment only once for a sender_batch_id that is used within 30 days.

    Maximum length: 256.

  • recipient_type

    string

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

    Maximum length: 13.

  • email_subject

    string

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

    Maximum length: 255.

  • email_message

    string

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

    Maximum length: 1000.

  • note

    string

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

    Maximum length: 1000.

sender_batch_header_response

  • sender_batch_id

    string

    The sender-specified ID number. Tracks the payout in an accounting system.
    Note: PayPal does not process duplicate payouts. If you specify a sender_batch_id that was used in the last 30 days, the API rejects the request with an error message that shows the duplicate sender_batch_id and includes a HATEOAS link to the original payout with the same sender_batch_id.
    If you receive an HTTP 5nn status code, you can safely retry the request with the same sender_batch_id. The API completes a payment only once for a sender_batch_id that is used within 30 days.

    Maximum length: 256.

  • recipient_type

    enum

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

    string

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

    Maximum length: 255.

  • email_message

    string

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

    Maximum length: 1000.

transaction_status

  • transaction_status

    enum

    The item transaction status. The possible values are:
    • NEW. Your request for a payout was received.
    • SUCCESS. Funds have been credited to the recipient’s account.
    • DENIED. This payout was denied, so funds have not been deducted from your account.
    • PENDING. Your payout request was received and will be processed.
    • FAILED. This payout request has failed, so funds were not deducted from the sender’s account.
    • 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.

Additional API information

Error messages

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

  • ACCOUNT_RESTRICTED

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

  • ACCOUNT_UNCONFIRMED_EMAIL

    You need to be a verified PayPal account holder to send payouts. You can verify your account by confirming your email and your bank account or credit card. Contact your account manager or our customer service team for assistance. To send payouts, you must be a verified PayPal account holder. To verify your account, confirm your email and your bank account or credit card. For assistance, contact your account manager or our customer service team.

  • AUTHORIZATION_ERROR

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

  • BATCH_NOT_COMPLETED

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

  • CLOSED_MARKET

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

  • CURRENCY_COMPLIANCE

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

  • CURRENCY_NOT_SUPPORTED_FOR_RECEIVER

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

  • DUPLICATE_ITEM

    This transaction is duplicated in this batch. Please check the Ref_ID / Sender_Item_ID. This transaction is duplicated in this batch. Verify the reference ID and sender item ID.

  • GAMER_FAILED_COUNTRY_OF_RESIDENCE_CHECK

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

  • GAMER_FAILED_FUNDING_SOURCE_CHECK

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

  • GAMING_INVALID_PAYMENT_FLOW

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

  • INSUFFICIENT_FUNDS

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

  • INTERNAL_ERROR

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

  • ITEM_ALREADY_CANCELLED

    This payout request has already been cancelled. This payout request has already been cancelled.

  • ITEM_CANCELLATION_FAILED

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

  • ITEM_INCORRECT_STATUS

    You can only cancel items that are unclaimed. You can only cancel items that are unclaimed.

  • MALFORMED_REQUEST_ERROR

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

  • NEGATIVE_BALANCE

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

  • NON_HOLDING_CURRENCY

    Your account does not have a PayPal balance in this currency. Try again with a currency that has funds in your PayPal account, or change your account settings to this currency. Your account does not have a PayPal balance in this currency. Try the request again with a currency that has funds in your PayPal account, or change your account settings to this currency.

  • PENDING_RECIPIENT_NON_HOLDING_CURRENCY_PAYMENT_PREFERENCE

    This payout is pending because the recipient has set their account preferences to review credits in this currency. The recipient has been notified. Check back later for the status of this payout. This payout is pending because the recipient has set their account preferences to review credits in this currency. The recipient has been notified. Check back later for the status of this payout.

  • POS_LIMIT_EXCEEDED

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

  • RATE_LIMIT_VALIDATION_FAILURES

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

  • RECEIVER_ACCOUNT_LOCKED

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

  • RECEIVER_COUNTRY_NOT_ALLOWED

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

  • RECEIVER_STATE_RESTRICTED

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

  • RECEIVER_UNCONFIRMED

    The recipient’s email or phone number is unconfirmed. Any payments made to this account will be marked as Unclaimed until the recipient confirms their account information. Funds will be returned to your account if they are not claimed within 30 days. The recipient’s email or phone number is unconfirmed. Any payments made to this account are marked as unclaimed until the recipient confirms their account information. If the funds are not claimed within 30 days, they will be returned to your account.

  • RECEIVER_UNREGISTERED

    The recipient for this payout does not have a PayPal account. A link to sign up for a PayPal account has been sent to the recipient, however, if the recipient does not claim this payout within 30 days, the funds will be returned to your account. 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 will be returned to your account.

  • RECEIVER_YOUTH_ACCOUNT

    We were not able to send a payout because the recipient has a youth account. Please check with the recipient for an alternate account to receive the payout. The payout could not be sent because the recipient has a youth account. Check with the recipient for an alternate account to receive the payout.

  • RECEIVING_LIMIT_EXCEEDED

    The recipient cannot accept this payout, because it exceeds the amount they can receive at this time. Please resubmit your payout request for a different amount. The recipient cannot accept this payout, because it exceeds the amount they can receive at this time. Resubmit your payout request for a different amount.

  • REFUSED_ACCESS_DENIED

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

  • RECEIVER_REFUSED

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

  • REGULATORY_BLOCKED

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

  • REGULATORY_PENDING

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

  • REQUIRED_SCOPE_MISSING

    The access token doesn't have the required scope. You'll need to use the access token with the correct scope to send a payout. The access token does not have the required scope. To send a payout, use an access token with the correct scope.

  • RISK_DECLINE

    This transaction was declined due to risk concerns. This transaction was declined due to risk concerns.

  • SELF_PAY_NOT_ALLOWED

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

  • SENDER_ACCOUNT_LOCKED

    You can’t send a payout now, because your account is locked or inactive. Contact your account manager or our customer service team for assistance. You cannot send a payout because your account is locked or inactive. For assistance, contact your account manager or our customer service team.

  • SENDER_ACCOUNT_UNVERIFIED

    To send a payout, you need to have a verified PayPal account. You can verify your account by confirming your bank account or credit card. Contact your account manager or our customer service team for assistance. To send a payout, you must have a verified PayPal account. To verify your account, confirm your bank account or credit card. For assistance, contact your account manager or our customer service team.

  • SENDER_STATE_RESTRICTED

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

  • SPENDING_LIMIT_EXCEEDED

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

  • TRANSACTION_DECLINED_BY_TRAVEL_RULE

    Your payout request does not comply with travel rule regulations. To send this payout, you’ll need to update and verify your account information. Contact your account manager or our customer service team for assistance. Your payout request does not comply with travel rule regulations. To send this payout, you must update and verify your account information. For assistance, contact your account manager or our customer service team.

  • TRANSACTION_LIMIT_EXCEEDED

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

  • UNDEFINED

    An error occurred while processing this payout request. Try again in a few minutes, or try resending as part of a new request or file. An error occurred while processing this payout request. Try the request again in a few minutes, or make a new request or send a new file.

  • UNVERIFIED_RECIPIENT_NOT_SUPPORTED

    This payout request was not completed because the recipient has not verified their account. Your account is only allowed to send payout to verified accounts. This payout request was not completed because the recipient has not verified their account. Your account is only allowed to send payout to verified accounts.

  • USER_BUSINESS_ERROR

    An error occurred while processing this payout request. For batch processing, try again with a different sender_batch_ID. For single payout items, try again with email or payer ID as recipient type. 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 the recipient type.

  • USER_COUNTRY_NOT_ALLOWED

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

  • USER_FUNDING_SOURCE_INELIGIBLE

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

  • ZERO_AMOUNT

    Please provide a valid payment amount. Provide a valid payment amount.

Feedback