Skip to main content
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 send payouts to PayPal accounts and Venmo users.

​
Prerequisites

​
Send payouts

You can use the procedures in this section to send payouts using the large-batch file transfer.

​
1. Create input file

  1. Add a summary line: Follow the required format and add a summary line as the first row of your file.
  2. Add payout records: Follow the required format and add each payment as a separate row.
  3. Name your file using this pattern: pp_payouts_<epoch_time>_<reference_name><format>
    Example: 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.

​
Summary line format

Sample summary line
PAYOUT_SUMMARY,1500.75,USD,5,"Thank you, ""Top Seller""!",Payout for May
FieldDescriptionNotes
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: USD
Max 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 May
Max length: 1000 characters

​
Payout item row format

Sample payout line items
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
If you skip any optional fields, add commas to keep the columns in the correct order.
FieldDescriptionNotes
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: USD
Max length: 3 characters
Reference IDUnique identifier for each payout item.Use letters, numbers, underscore (_), or hyphen (-).

Example: REF_ID_1
Max 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 work
Max length: 1000 characters
Social feed privacy
Venmo only		Visibility setting for the Venmo recipient’s social feed.Default value: PRIVATE

Possible 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.png
Max 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.png
Max length: 2000 characters
Purpose
Reason for the transaction.Default value: GOODS

Possible values:
• AWARDS
• PRIZES
• DONATIONS
• GOODS
• SERVICES
• REBATES
• CASHBACK
• DISCOUNTS
• NON_GOODS_OR_SERVICES

​
2. Upload input file

You can use your Sandbox DropZone credentials, log into the DropZone account, test your file upload, and rectify errors if any. You can then use your Production DropZone credentials and upload your file for payouts.
  1. Connect to PayPal’s DropZone on the SFTP server using your SFTP login details.
  2. Go to the 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.
  3. Review the report to verify the file validation status.

​
Acknowledgment reports

ReportFile name suffixWhat it meansWhat to do
Accepted (ACK)_ack.csvFile is ready for processing.Wait for PayPal to process your payouts.
Not Accepted (NACK)_nack.csvFile has errors.Fix the errors and upload a new file with a different name.
Duplicate (DUPS)_dups.csvFile 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
    • Columns: Entry type, Currency code, Error code, Error message
    Example
    PAYOUT_SUMMARY,USD,INVALID_CURRENCY,Invalid currency code in line 3
  • Item-level error line
    • Columns: Payout type, Line number, Reference ID, Error code, Error message
    Example
    PAYOUT,3,REF_ID_1,INVALID_CURRENCY,Invalid currency code
For a complete list of possible error codes, see File validation errors. ACK report The ACK report shows:
  • The date and time (in UTC) when PayPal received your file.
  • Your original file name (without the ending).
  • The status: ACCEPTED_FOR_PROCESSING.
Example
2018-02-26T05:48:53Z,pp_payouts_6627887729_testfile,ACCEPTED_FOR_PROCESSING

​
3. Review stage reports

As PayPal processes payouts, stage reports are saved in your Outgoing folder to help you track and match your payments.
ReportWhen you get itWhat it showsWhat to do
Part File reportAfter 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 reportAfter 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 report31 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.
If a recipient does not claim their payment within 30 days, PayPal automatically returns the money to your account.

​
Report file format

The Part, Out or Interim, and Final reports are .csv files that include the following columns:
  • Reference ID
  • Payout item ID
  • Transaction ID
  • Recipient name
  • Recipient identifier
  • Currency code
  • Payout amount
  • Fee
  • Total
  • Transaction status
  • Error enum
  • Error message
  • Processed time
  • Claimed time (applicable for unilateral case)
Sample report entries
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:16Z

​
Reference

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

​
File validation steps and outcomes

The following table summarizes the various file validation steps and the possible results:
Validation stepWhat PayPal checksResult
File existsChecks if your file is in the folder.NACK if missing
File not emptyChecks if your file has content and is not broken.NACK if empty or broken
File encodingMakes sure your file uses UTF-8 text format.NACK if wrong format
File formatChecks for correct file type (.csv or .csv.gz) and proper columns.NACK if wrong
File matchesChecks if summary totals match your payment details.NACK if they do not match
File nameMakes sure your file name follows the rules.NACK or DUPS if wrong
Duplicate fileChecks if you already sent a file with this name.DUPS if already used
Sandbox limitChecks if you have too many items (sandbox only).NACK if too many
Summary and line checksChecks for: text length, valid currency, one summary only, summary in first line, correct payment count, valid purpose.NACK if wrong
Payment detailsChecks each payment line has all needed info.NACK if missing info
Amount and currencyMakes sure amounts and currency codes are valid.NACK if wrong

​
File validation errors

The following table summarizes the file validation errors that PayPal may find in your payout file:
ErrorDescription
DUPLICATE_REF_IDReference IDs must be unique within an input file.
EMAIL_MESSAGE_EXCEEDED_MAX_SIZEThe email message exceeded the maximum character limit. The limit is 1000.
EMAIL_SUBJECT_EXCEEDED_MAX_SIZEThe email subject exceeded the maximum character limit. The limit is 255.
ENCODING_ERRORThe payout input file is not in UTF-8 format.
FILE_EMPTY_OR_CORRUPTThe payout input file is empty or corrupt and cannot be processed.
FILE_NOT_FOUNDThe file does not exist in the source folder. Contact our customer support.
FILE_SIZE_ERRORThe payout input file is empty.
GZ_FILE_CORRUPT_ERRORThe payout input file is corrupt or has a checksum issue.
INVALID_CURRENCYThe currency code is invalid.
INVALID_FILE_FORMATThe 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_NAMEThe format of the file name is invalid.
INVALID_FIRST_COLUMNThe first column entry in the summary must be PAYOUT_SUMMARY. For an item record, this must be PAYOUT.
INVALID_REF_ID_FORMATThe reference ID must be alphanumeric. The maximum character limit is 63.
INVALID_SUMMARY_LINE_POSITIONThe payout summary record is missing from the first line in the payout input file.
MANDATORY_COLUMN_MISSINGThe file is missing mandatory columns. Please enter the required information and retry the Payout.
MULTI_CURRENCY_NOT_SUPPORTEDThe payout input file has more than one currency.
MULTIPLE_SUMMARY_RECORDSThe payout input file should contain only one summary record.
PAYOUT_AMOUNT_INVALID_FORMATThe payout amount must use a decimal. Other special characters are not allowed.
PAYOUT_AMOUNT_NON_POSITIVEThe payout amount must be greater than zero.
SANDBOX_LIMIT_ERRORThe number of items in the file exceeds the sandbox file limit (sandbox only).
SCHEDULED_TIME_ERRORThe payout can be scheduled a maximum of seven days in advance.
SUMMARY_AMOUNT_INVALID_FORMATThe summary amount must be a decimal. Other special characters are not allowed.
SUMMARY_AMOUNT_NON_POSITIVEThe total payout amount in the summary line must be greater than zero.
SUMMARY_AND_PAYOUT_MATCH_CONFLICTThe payout amount in the summary line does not match the total item value.
SUMMARY_LINES_NON_INTEGERThe total number of payments field in the summary line must be an integer.
SUMMARY_LINES_NON_POSITIVEThe total number of payments field in summary line must be greater than zero.
SUMMARY_MISSINGThe summary line is missing from the payout input file.
TOTAL_PAYMENTS_MISMATCHThe TOTAL_NO_OF_PAYMENTS in the PAYOUTS_SUMMARY row must match the total records in the payout input file.
INVALID_PURPOSEThe purpose specified for the transaction is invalid.