On this page
No Headings
Last updated: September 10, 2026
You can use this pattern to pay more than 15,000 people at once with a single payment file. Common use-cases for this functionality include payroll payouts, rebate payouts, reward payouts, and affiliate program payouts.
You can use the procedures in this section to send payouts using the large-batch file transfer.
pp_payouts_<epoch_time>_<reference_name><format> pp_payouts_1728883200_batch1.csv
pp_payouts: Always use these exact words in lowercase.<epoch_time>: A special time code (from the past or up to 7 days ahead).<reference_name>: Your chosen name using letters, numbers, underscore (_), or hyphen (-). Maximum: 63 characters.<format>: File type - use .csv or .csv.gz.PAYOUT_SUMMARY,1500.75,USD,5,"Thank you, ""Top Seller""!",Payout for May| Field | Description | Notes |
|---|---|---|
| Entry type Required | The first line must always contain PAYOUT_SUMMARY. | Use uppercase only. Example: PAYOUT_SUMMARY |
| Total payout amount Required | Total of all payout items. | Must be in decimal format. Currency symbols not allowed. Cannot be empty or zero. Example: 1500.75 |
| Currency Required | Three-letter ISO 4217 currency code. Each file must contain only one currency type. | Use separate files for different currencies. Example: USDMax length: 3 characters |
| Total payments Required | Total number of payout items in the file. | Use numbers only. Example: 5 |
| Email subject | A standard subject line in the email notification sent to all recipients for each payout item. | If text has commas or special characters, use double quotes (") around it. If text has quotes, double them ("") and wrap in quotes. Example: "Thank you, ""Top Seller""!"Max length: 256 characters |
| Email message | A standard message included in the email notification sent to all recipients for each payout item. | If text has commas or special characters, use double quotes (") around it. If text has quotes, double them ("") and wrap in quotes. Example: Payout for MayMax length: 1000 characters |
PAYOUT,test@paypal.com,1000.50,USD,REF_ID_1,Thanks for your work
PAYOUT_VENMO,5551232368,500.25,USD,REF_ID_2,"Congrats!"
PAYOUT,test@paypal.com,1,USD,REF_ID_1,NOTE_1,,,AWARDS| Field | Description | Notes |
|---|---|---|
| Recipient wallet Required | Target wallet for the payout. | Use uppercase only. Possible values: • PAYOUT• PAYOUT_VENMO |
| Recipient identifier Required | Identifier for the payout recipient based on the wallet type. | PayPal: Recipient’s PayPal-associated email address, phone number, or encrypted PayPal account number. Venmo: Recipient’s US mobile number or Venmo handle. Example: test@paypal.com |
| Payout amount Required | Amount to send. | Use decimal format only (local currency formats are not supported). Cannot be empty or zero. Example: 100.50 |
| Currency Required | Three-letter ISO 4217 currency code. Each file must contain only one currency type. | Use separate files for different currencies. Example: USDMax length: 3 characters |
| Reference ID | Unique identifier for each payout item. | Use letters, numbers, underscore (_), or hyphen (-). Example: REF_ID_1Max length: 30 characters |
| Item-level note | Custom note included in the email for each payout item. | If text has commas or special characters, use double quotes (") around it. If text has quotes, double them ("") and wrap in quotes. Example: Thanks for your workMax length: 1000 characters |
| Social feed privacy Venmo only | Visibility setting for the Venmo recipient’s social feed. | Default value: PRIVATEPossible values: • PUBLIC• FRIENDS_ONLY• PRIVATE |
| Holler URL Deprecated Venmo only | URL of a Holler sticker to include with the Venmo message. | Example: https://example.com/sticker.pngMax length: 151 characters |
| Logo URL Venmo only | URL of the business logo shown in the Venmo feed. | Image uploaded at the access URL must be a square image of max size 1024 × 1024 px. Example: https://example.com/logo.pngMax length: 2000 characters |
| Purpose | Reason for the transaction. | Default value: GOODSPossible values: • AWARDS• PRIZES• DONATIONS• GOODS• SERVICES• REBATES• CASHBACK• DISCOUNTS• NON_GOODS_OR_SERVICES |
Incoming folder on the server and upload your file. PayPal checks the file and creates an acknowledgement report. See File validation steps and outcomes. PayPal places the report in the Outgoing folder.| Report | File name suffix | What it means | What to do |
|---|---|---|---|
| Accepted (ACK) | _ack.csv | File is ready for processing. | Wait for PayPal to process your payouts. |
| Not Accepted (NACK) | _nack.csv | File has errors. | Fix the errors and upload a new file with a different name. |
| Duplicate (DUPS) | _dups.csv | File name already used. | Change the file name and upload again. |
NACK report
The NACK report consists of two types of errors lines.
Summary error line
PAYOUT_SUMMARY,USD,INVALID_CURRENCY,Invalid currency code in line 3Item-level error line
PAYOUT,3,REF_ID_1,INVALID_CURRENCY,Invalid currency codeFor a complete list of possible error codes, see File validation errors.
ACK report
The ACK report shows:
ACCEPTED_FOR_PROCESSING.2018-02-26T05:48:53Z,pp_payouts_6627887729_testfile,ACCEPTED_FOR_PROCESSINGAs PayPal processes payouts, stage reports are saved in your Outgoing folder to help you track and match your payments.
| Report | When you get it | What it shows | What to do |
|---|---|---|---|
| Part File report | After part of your file is processed. | Shows results for the processed part. Large files may have multiple part files as PayPal processes them in sections. | Check each part file to track progress and fix problems as they appear. |
| Out or Interim report | After your whole file is processed. | Shows results for all payments in your file, including status and errors. | Use this to check your records and confirm all payments were sent. |
| Final report | 31 days after the Interim report. | Shows the final status of payments that were not claimed. | Check which payments were not claimed and decide what to do next. |
The Part, Out or Interim, and Final reports are .csv files that include the following columns:
REF_ID_1,SX3QT8QVBVE4L,35P324312A142790D,,test-1@paypal.com,USD,4.82,0.25,5.07,UNCLAIMED,RECEIVER_UNREGISTERED,Receiver is unregistered,2018-01-16T10:33:22Z
REF_ID_2,HP3B9BRJYMKRU,1H080416VK328525U,,bjonny-us4@paypal.com,USD,4.93,0.25,5.18,SUCCESS,,,2018-01-16T10:33:20Z
REF_ID_3,BUPR735Z5CJBJ,7FB53422KY616915S,,test-3@paypal.com,USD,2.77,0.25,3.02,UNCLAIMED,RECEIVER_UNREGISTERED,Receiver is unregistered,2018-01-16T10:33:19Z
REF_ID_6,AU49JFTXWUQ8Q,7RG81691FV520321P,,test-1@paypal.com,USD,0.86,0.25,1.11,UNCLAIMED,RECEIVER_UNREGISTERED,Receiver is unregistered,2018-01-16T10:33:20Z
REF_ID_7,C5USHNEDMCXWL,,,bjonny-us9@paypal.com,USD,1.71,0,1.71,FAILED,ACCOUNT_RESTRICTED,User is restricted,2018-01-16T10:33:16ZYou can use the following information to understand the file validation process and errors. You can review the errors, fix them, and upload your payout file again.
The following table summarizes the various file validation steps and the possible results:
| Validation step | What PayPal checks | Result |
|---|---|---|
| File exists | Checks if your file is in the folder. | NACK if missing |
| File not empty | Checks if your file has content and is not broken. | NACK if empty or broken |
| File encoding | Makes sure your file uses UTF-8 text format. | NACK if wrong format |
| File format | Checks for correct file type (.csv or .csv.gz) and proper columns. | NACK if wrong |
| File matches | Checks if summary totals match your payment details. | NACK if they do not match |
| File name | Makes sure your file name follows the rules. | NACK or DUPS if wrong |
| Duplicate file | Checks if you already sent a file with this name. | DUPS if already used |
| Sandbox limit | Checks if you have too many items (sandbox only). | NACK if too many |
| Summary and line checks | Checks for: text length, valid currency, one summary only, summary in first line, correct payment count, valid purpose. | NACK if wrong |
| Payment details | Checks each payment line has all needed info. | NACK if missing info |
| Amount and currency | Makes sure amounts and currency codes are valid. | NACK if wrong |
The following table summarizes the file validation errors that PayPal may find in your payout file:
| Error | Description |
|---|---|
DUPLICATE_REF_ID | Reference IDs must be unique within an input file. |
EMAIL_MESSAGE_EXCEEDED_MAX_SIZE | The email message exceeded the maximum character limit. The limit is 1000. |
EMAIL_SUBJECT_EXCEEDED_MAX_SIZE | The email subject exceeded the maximum character limit. The limit is 255. |
ENCODING_ERROR | The payout input file is not in UTF-8 format. |
FILE_EMPTY_OR_CORRUPT | The payout input file is empty or corrupt and cannot be processed. |
FILE_NOT_FOUND | The file does not exist in the source folder. Contact our customer support. |
FILE_SIZE_ERROR | The payout input file is empty. |
GZ_FILE_CORRUPT_ERROR | The payout input file is corrupt or has a checksum issue. |
INVALID_CURRENCY | The currency code is invalid. |
INVALID_FILE_FORMAT | The input file contains characters, columns, or details that are not required for processing payouts. Remove these characters, columns, or details and upload the file. |
INVALID_FILE_NAME | The format of the file name is invalid. |
INVALID_FIRST_COLUMN | The first column entry in the summary must be PAYOUT_SUMMARY. For an item record, this must be PAYOUT. |
INVALID_REF_ID_FORMAT | The reference ID must be alphanumeric. The maximum character limit is 63. |
INVALID_SUMMARY_LINE_POSITION | The payout summary record is missing from the first line in the payout input file. |
MANDATORY_COLUMN_MISSING | The file is missing mandatory columns. Please enter the required information and retry the Payout. |
MULTI_CURRENCY_NOT_SUPPORTED | The payout input file has more than one currency. |
MULTIPLE_SUMMARY_RECORDS | The payout input file should contain only one summary record. |
PAYOUT_AMOUNT_INVALID_FORMAT | The payout amount must use a decimal. Other special characters are not allowed. |
PAYOUT_AMOUNT_NON_POSITIVE | The payout amount must be greater than zero. |
SANDBOX_LIMIT_ERROR | The number of items in the file exceeds the sandbox file limit (sandbox only). |
SCHEDULED_TIME_ERROR | The payout can be scheduled a maximum of seven days in advance. |
SUMMARY_AMOUNT_INVALID_FORMAT | The summary amount must be a decimal. Other special characters are not allowed. |
SUMMARY_AMOUNT_NON_POSITIVE | The total payout amount in the summary line must be greater than zero. |
SUMMARY_AND_PAYOUT_MATCH_CONFLICT | The payout amount in the summary line does not match the total item value. |
SUMMARY_LINES_NON_INTEGER | The total number of payments field in the summary line must be an integer. |
SUMMARY_LINES_NON_POSITIVE | The total number of payments field in summary line must be greater than zero. |
SUMMARY_MISSING | The summary line is missing from the payout input file. |
TOTAL_PAYMENTS_MISMATCH | The TOTAL_NO_OF_PAYMENTS in the PAYOUTS_SUMMARY row must match the total records in the payout input file. |
INVALID_PURPOSE | The purpose specified for the transaction is invalid. |
Use Web UI
Learn how to send up to 5,000 payments for a file using Payouts Web. Use .csv files to manage bulk payouts efficiently and integrate with PayPal's payment system.
Use Payouts API
Send payouts programmatically using the Payouts API, including creating a payout batch, tracking status, handling errors, and testing your integration.