Use large-batch file transfer

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

• Complete all mandatory steps to get started.
• Ensure your PayPal business account is set up.
• Ensure to fund your business account.

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

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: 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,[e-mail],1000.50,USD,REF_ID_1,Thanks for your work
PAYOUT_VENMO,5551232368,500.25,USD,REF_ID_2,"Congrats!"
PAYOUT,[e-mail],1,USD,REF_ID_1,NOTE_1,,,AWARDS

If you skip any optional fields, add commas to keep the columns in the correct order.

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: [e-mail]
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 ID	Unique 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

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

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

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.

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,,[e-mail],USD,4.82,0.25,5.07,UNCLAIMED,RECEIVER_UNREGISTERED,Receiver is unregistered,2018-01-16T10:33:22Z
REF_ID_2,HP3B9BRJYMKRU,1H080416VK328525U,,[e-mail],USD,4.93,0.25,5.18,SUCCESS,,,2018-01-16T10:33:20Z
REF_ID_3,BUPR735Z5CJBJ,7FB53422KY616915S,,[e-mail],USD,2.77,0.25,3.02,UNCLAIMED,RECEIVER_UNREGISTERED,Receiver is unregistered,2018-01-16T10:33:19Z
REF_ID_6,AU49JFTXWUQ8Q,7RG81691FV520321P,,[e-mail],USD,0.86,0.25,1.11,UNCLAIMED,RECEIVER_UNREGISTERED,Receiver is unregistered,2018-01-16T10:33:20Z
REF_ID_7,C5USHNEDMCXWL,,,[e-mail],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 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

File validation errors

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.