Use large-batch file transfer

You can use this method to pay more than 15,000 recipients at once with a single payment file.

Typical use-cases: Payroll payouts, rebate payouts, reward payouts, or affiliate program payouts.

Prerequisites

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

Send payouts

1. Create input file

1. Add a summary line: Follow the required format and add a summary line as the first row of your input file.
2. Add payout records as line items: Follow the required format and add each payout you want to send as a separate row.
3. Use the naming convention pp_payouts_<epoch_time>_<reference_name><format> and save the input file. Sample file name: pp_payouts_1728883200_batch1.csv
   • pp_payouts: Static value. Ensure it is in lowercase.
   • <epoch_time> is an epoch timestamp (past or up to 7 days in the future from the upload date).
   • <reference_name>: Alphanumeric (a-z, A-Z, 0-9) value. Can contain underscore (_), or hyphen (-). Maximum: 63 characters.
   • <format>: .csv or .csv.gz.

Summary line format

Sample summary line

PAYOUT_SUMMARY,1500.75,USD,2,"You got paid","Payout for May"

Field	Description	Example	Max length	Notes
Entry type	Static value	PAYOUT_SUMMARY	-	Uppercase only
Total payout amount	Total of all payout items	1500.75	-	Digits, decimal point (.)
Currency code	Currency for the payout (one per file)	USD	3	Uppercase letters only
Total payments	Number of payout items in the file	5	-	Digits only
Email subject	Subject for recipient email (same for all recipients)	"You got paid"	256	Use double quotes (") if needed; use two double quotes ("") to escape a double quote character inside the value
Email message	Note in the email notification (same for all recipients)	"Payout for May"	1000	Use double quotes (") if needed; use two double quotes ("") to escape a double quote character inside the value

Payout item row format

Sample payout line items

PAYOUT,[email protected],1000.50,USD,REF_ID_1,"Thanks for your work"
PAYOUT_VENMO,5551232368,500.25,USD,REF_ID_2,"Congrats!"
PAYOUT,[email protected],1,USD,REF_ID_1,NOTE_1,,,,AWARDS

Note: If you omit any optional fields, include commas to maintain the correct column order.

Field	Description	Example	Max length	Notes
Payout type	PAYOUT for PayPal recipients or PAYOUT_VENMO for Venmo recipients	PAYOUT	-	Uppercase only
Recipient identifier	Recipient's email, phone, Venmo handle, or encrypted PayPal ID	[email protected]	-	-
Payout amount	Amount for each payout item (decimal format)	100.50	-	Digits, decimal point (.)
Currency	Currency for the payout item	USD	3	One currency per file
Reference ID	Unique identifier for each payout item	REF_ID_1	30	Use letters (a-z, A-Z), digits (0-9), underscore (_), or hyphen (-)
Note	Optional note for each payout item	Thanks for your work	1000	Use double quotes (") if needed; use two double quotes ("") to escape a double quote character inside the value
Social feed privacy (Venmo only)	Controls who can see the payment in the recipient's Venmo social feed: PUBLIC, FRIENDS_ONLY, or PRIVATE	PRIVATE	-	Uppercase only, defaults to PRIVATE
Holler URL (deprecated) (Venmo only)	Optional. Link to a Holler sticker that displays with the payout message	-	151	Must be a valid URL (http or https)
Logo URL (Venmo only)	Optional. Link to a square logo (max 1024×1024 px) to add or update your business profile image in the recipient’s Venmo feed	-	2000	Must be a valid URL (http or https)
Purpose	Optional value to denote the transaction purpose. Allowed values: AWARDS, PRIZES, DONATIONS, GOODS, SERVICES, REBATES, CASHBACK, DISCOUNTS, NON_GOODS_OR_SERVICES	AWARDS	-	Defaults to GOODS

2. Upload the input file

1. Connect to PayPal’s DropZone on the SFTP server with your SFTP user credentials.
2. Go to the Incoming folder on the server and upload your input file. PayPal validates the file and generates an acknowledgement report. See File validation steps and outcomes.
3. Check the Outgoing folder on the server for the acknowledgment report that shows your file’s validation status.

Acknowledgment reports

Each acknowledgment report file name matches your input file name and uses a suffix to indicate its type:

• _ack.csv for ACK (accepted for processing)
• _nack.csv for NACK (not accepted; errors found - fix errors and upload a new file with a unique name)
• _dups.csv for DUPS (duplicate file name - change the file name and upload again)

Note: If you send a file with content that matches a file you sent within seven days, you receive a NACK file. Contact your PayPal Account Manager to override this feature.

Sample acknowledgment report file names

pp_payouts_1234567890_batch1_ack.csv
pp_payouts_1234567890_batch1_nack.csv
pp_payouts_1234567890_batch1_dups.csv

NACK report

The NACK report may include two types of error lines. For a complete list, see File validation errors.

• Summary error line:

  • Columns: Entry type, Currency code, Error enum, Error description
  • Example:

    PAYOUT_SUMMARY,USD,INVALID_CURRENCY,Invalid currency code in line 3

• Item-level error line:

  • Columns: Payout type, Line number, Reference ID, Error enum, Error description
  • Example:

    PAYOUT,3,REF_ID_1,INVALID_CURRENCY,Invalid currency code

ACK report

The ACK report contains the following information:

• The UTC date and time when PayPal acknowledged your file.
• The original input file name (without the suffix).
• The status, which is always ACCEPTED_FOR_PROCESSING.

2018-02-26T05:48:53Z,pp_payouts_6627887729_testfile,ACCEPTED_FOR_PROCESSING

3. Review stage-wise reports

As PayPal processes payouts, stage-wise reports are placed in your Outgoing folder to help monitor and reconcile your payouts.

Report	Stage	Description	Action
Part File report	After a portion of the input file is processed	Contains transaction-level results for the processed segment. For very large batches, multiple part files may be created as PayPal processes the file in segments.	Review each part file to monitor interim results and address issues as they arise.
Out or Interim report	After all parts of the file are processed	Summarizes the results for all transactions in the batch, including payout status and any errors.	Use this file to reconcile your records and confirm the completion of the payout batch.
Final report	31 days after the Interim file	Provides the ultimate status of any unclaimed transactions.	Check the final status of unclaimed transactions and take any necessary follow-up action.

Note: If a recipient does not claim their payout within 30 days of the payout date, PayPal automatically returns the money to your account.

Report file format

The Part, Out or Interim, and Final reports use the .csv format with the following information:

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

Next step

Test large-batch file transfer and move to production.

Reference

File validation steps and outcomes

Validation step	Description	Outcome
File existence	Checks if the file exists in the source folder	NACK if missing
File empty	Checks if the file is empty or corrupt	NACK if empty/corrupt
File encoding format	Verifies the file is in UTF-8 encoding	NACK if invalid
File format	Ensures the file is in the correct format (.csv or .csv.gz) and contains only required columns and characters	NACK if invalid
File integrity	Validates that the payout summary matches the payout item record details	NACK if mismatch
Filename convention check	Ensures the file name follows required naming rules	NACK or DUPS if invalid
Duplicate file detection	Detects if a file with the same name was previously uploaded	DUPS if duplicate
Sandbox items limit	Checks if the number of items exceeds the sandbox file limit (sandbox only)	NACK if exceeded
Summary and line item checks	Checks for: character length limits, invalid/missing currency, multiple summary records, missing PAYOUT_SUMMARY, summary not in first line, total number of payments mismatch, invalid purpose value	NACK if invalid
Payout item validation	Validates each payout line for required fields, data types, and uniqueness	NACK if invalid
Amount and currency validation	Ensures payout amounts and currency codes are valid and consistent	NACK if invalid

File validation errors

The following errors may occur when PayPal validates your payout input file. After you've fixed the errors, retry the payout.

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 has been removed from 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 aren't 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 aren't 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 doesn’t 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.