payouts

Large Batch Payouts

Large Batch Payouts enables you to simultaneously send payouts to an unlimited amount of recipients by creating a payouts input file and placing it in folder on a secure FTP server.

How it works

How large batch payouts work

  1. You create a payouts input file and share it in a folder tied to your account on PayPal's secure DropZone server.

  2. Payouts validates the input file. If the file passes the validation, Payouts sends you an ACK (acknowledgment) report and begins processing the file. If the file fails the validation, Payouts sends you a NACK (negative acknowledgment) report that explains the errors. You can correct any problems and resubmit the input file.

  3. Large files are processed in parts of up to 500,000 individual records. After each part of the input file is processed, Payouts provides a Part File report. When the entire file is completely processed, you receive an Out File report. The reports are available in your DropZone account.

    Note: After 30 days, you receive a Final report that contains the status for each individual record.

  4. Recipients are notified of the payout.

Prerequisites

To use Large Batch Payouts, you must have:

  1. A PayPal Business account with a confirmed email address and bank account. If you don't have a PayPal Business account, sign up now.

  2. Payouts enabled.

    1. US merchants—To enable Payouts, you can complete either of the following actions:
      1. Contact your Account Manager or PayPal customer support.
      2. Enable Payouts from My Account:
        1. Log in to the Developer Dashboard and go to My Account.
        2. Under Permissions name, locate Payouts and click the Enable link.
        3. Click Enable, complete the form and click Submit. When you've been approved, you'll receive an email from a PayPal representative.
    2. Non-US merchants—To enable Payouts, contact your Account Manager or PayPal customer support.

1. Set up a DropZone account

You can choose to first test your integration in the PayPal sandbox and send mock payouts or go straight to production and send live payouts. Follow the steps to set up a sandbox environment or production environment.

Sandbox environment

Use the PayPal sandbox to:

  • Simulate file transfer to a designated folder on PayPal’s DropZone server via SFTP.
  • Validate the file name, file format, checksum and file integrity.
  • Test Out File reports and reconciliations.

To set up your sandbox environment:

  1. Contact your account manager or PayPal customer support and provide the following information:

    • PayPal account ID
    • Your public ssh key
    • Your public outgoing IP address. PayPal uses your IP address to white list your account in the sandbox.

    PayPal creates your SFTP account and provides your sandbox user name.

  2. To access your sandbox SFTP account, use the SFTP tool of your choice and the following information:

    • Sandbox endpoint/URL: dropzone.es-ext.paypalcorp.com
    • Destination host port: 22
    • Sandbox user name
    • Public ssh key

Next, set up your production environment to send live payouts or create an input file.

Production environment

The Payouts production environment enables you to send live payouts.

Note: Transactions performed in production are live transactions and money is debited from your PayPal balance and credited to each recipient’s PayPal account. If the recipient does not have an active PayPal account and does not claim the money within 30 days from the payout date, then the money is returned to your account.

To set up your production environment:

  1. Contact your account manager or PayPal customer support and provide the following information to create your SFTP account:

    • PayPal account ID
    • Production ssh public key

    Note: You must create a new set of ssh keys for your production environment.

    PayPal creates your SFTP account and provides your production user name.

  2. To access your production SFTP account, use the SFTP tool of your choice and the following information:

    • Production endpoint/URL for the SFTP login: dropzone.paypal.com
    • Destination host port: 22
    • Production user name
    • Publish ssh key

Next, create an input file and place it in your Incoming folder.

2. Create an input file

Create a comma separated value (.csv) input file that includes a Summary line and information for each individual payout item. You can use a spreadsheet, text editor, or database application to create the input file.

When your file is complete, it looks similar to this example:

PAYOUT_SUMMARY,17.9,USD,5,"Hey, You got a Payout",Payout for
PAYOUT,test-1@paypal.com,4.82,USD,REF_ID_1,NOTE_1
PAYOUT,test-2@paypal.com,4.93,USD,REF_ID_2,NOTE_2
PAYOUT,test-3@paypal.com,2.77,USD,REF_ID_3,NOTE_3
PAYOUT,test-4@paypal.com,3.51,USD,REF_ID_4,NOTE_4
PAYOUT,test-5paypal.com,1.87,USD,REF_ID_5,NOTE_5

2.a. Add the Summary line

The first line of the input file must contain a SUMMARY as shown in this example:

PAYOUT_SUMMARY, TOTAL_PAYOUT_AMOUNT, CURRENCY_CODE, TOTAL_NO_OF_PAYMENTS, EMAIL_SUBJECT, EMAIL_MESSAGE

Use this information to complete each field of the Summary:

Field Description
PAYOUT_SUMMARY
  • Static, case-sensitive value.
  • Must be upper case.
TOTAL_PAYOUT_AMOUNT
  • Cumulative value of individual items’ payout amount.
  • Must be in decimal format.
  • In the example above the value is 17.9.
CURRENCY_CODE
  • Currency for the payout, such as USD, EUR, and so on. Only one currency type is supported per input file.
TOTAL_NO_OF_PAYMENTS
  • Number of payout items in the file.
  • In the example above the item count is 5.
EMAIL_SUBJECT
  • The subject of the email that recipients receive as a payout notification.
  • If using a text editor to create your input file:
    • If an email subject contains a comma or other special character, enclose the subject in double quotes.
    • If the email subject contains a double quote, escape the double quotes with an additional set of double quotes and enclose the entire subject with double quotes. See Summary examples.
  • Max character length: 256
EMAIL_MESSAGE
  • A common note in the email notification sent to all recipients for all payout items.
  • If using a text editor to create your input file:
    • Notes with a comma or special character must be enclosed with double quotes. See Summary examples.
    • If the note contains a double quote, escape the double quote with an additional set of double quotes and enclose the entire note with double quotes.
  • Max character length: 1000

Summary examples

Follow these examples to create a valid Summary line:

Description Example
Contains EMAIL_SUBJECT and BATCH_LEVEL_NOTE. PAYOUT_SUMMARY,17.9,USD,5,You Got a Payout,Payout For
EMAIL_SUBJECT is empty. PAYOUT_SUMMARY,17.9,USD,5,,Payout For
BATCH_LEVEL_NOTE is empty PAYOUT_SUMMARY,17.9,USD,5,You Got a Payout,
BATCH_LEVEL_NOTE is missing. PAYOUT_SUMMARY,17.9,USD,5,You Got a Payout
EMAIL_SUBJECT and BATCH_LEVEL_NOTE is missing. PAYOUT_SUMMARY,17.9,USD,5
EMAIL_SUBJECT contains a comma. PAYOUT_SUMMARY,17.9,USD,5,"Hey, You got a Payout",Payout For
If using a text editor to create your input file and EMAIL_SUBJECT contains double quotation marks, escape the double quote with an additional set of double quotes and enclose the entire subject with double quotes. PAYOUT_SUMMARY,17.9,USD,5,"HEY, YOU GOT a ""PAYOUT""",Payout For

2.b. Add individual item records

Beginning with the second line of the input file, add a record for each individual payout item using this required format:

PAYOUT, RECIPIENT_EMAIL, PAYOUT_AMOUNT, CURRENCY_CODE, UNIQUE_REF_ID, ITEM_LEVEL_NOTE

Use this information to complete each field for an individual item record:

Fields Description
PAYOUT
  • Static, case-sensitive value.
  • Must be upper case.
RECIPIENT_EMAIL
  • The recipient identifier.
  • Use the recipient's email address or their encrypted PayPal account number.
PAYOUT_AMOUNT
  • Value of individual payout item.
  • Only use decimal format. Localized currency formats are not supported.
  • Must not be empty or a zero amount.
CURRENCY_CODE
  • Currency in which the payouts are sent.
  • Use a single currency per input file. Multiple currencies are not supported in a single input file.
  • In the example above the currency code is USD.
UNIQUE_REF_ID
  • Unique identifier for a payout item.
  • Must also be unique within the input file.
  • Must be alphanumeric [0-9, a-z, A-Z]. Only use the underscore (_) and hyphen (-) as special characters.
  • Maximum character length: 30
ITEM_LEVEL_NOTE
  • Customized note that can be sent in email notification for every payout item.
  • Use any special character or alphanumeric character.
  • For txt input files:
    • Notes with a comma or special character must be enclosed with double quotes.
    • If the note contains a double quote, escape the double quote with and an additional set of double quotes and enclose the entire note with double quotes. See Individual item record examples.
  • Maximum character length: 1000

Individual item record examples

Follow these examples to create valid individual item records:

Description Example
ITEM_LEVEL_NOTE is missing. PAYOUT,test-1@paypal.com,4.82,USD,REF_ID_1
ITEM_LEVEL_NOTE is empty. PAYOUT,test-1@paypal.com,4.82,USD,REF_ID_1,
ITEM_LEVEL_NOTE omits the comma. PAYOUT,test-1@paypal.com,4.82,USD,REF_ID_1,NOTE_1
ITEM_LEVEL_NOTE contains a comma or any other special character. If using a text editor to create your input file, enclose ITEM_LEVEL_NOTE with a double quote. PAYOUT,test-1@paypal.com,4.82,USD,REF_ID_1,"NOTE_1,test"
ITEM_LEVEL_NOTE contains a double quote. If using a text editor to create your input file, use double quotes to escape a note that contains a double quote. The example shows "23" escaped. PAYOUT,test-1@paypal.com,4.82,USD,REF_ID_1,"NOTE_1,test""23"""

2.c. Save the input file

Use this naming convention to save the file:

pp_payouts_epoch_time_reference_name.format

Where pp_payouts is static and must be lower-case. Variable fields in the file name include the following:

Field Description
epoch_time Use an epoch timestamp. Timestamps in the past are acceptable. Future timestamps must be within seven days from the time that you place the file on the DropZone server.
reference_name Must be alphanumeric [0-9, a-z, A-Z]. Only use the underscore (_) and hyphen (-) as special characters. Other special characters are not allowed. Maximum character length: 63
format Accepted formats: .csv, .csv.gz

3. Upload the input file

You can choose to upload and test your input file in your sandbox environment or go straight to your production environment to upload your input file and make live payouts. Once you upload the file, Payouts validates the file.

File validation

Payouts performs the following validations on your input file:

  • File name validation — Fails if the input file does not use the correct file naming convention.
  • Summary and line item validation — Fails if any of these conditions exist:
    • Currency field is empty or missing.
    • Currency uses a localized format.
    • Total number of payments field is empty or missing.
    • Contains an invalid currency code.
    • Character length surpasses the maximum values.
    • Invalid payout Summary format.
  • File integrity validation — Fails if the payout Summary does not match the payout item record details.
  • Duplicate file validation — Fails if the input file name is not unique. The file cannot match a previous input file name.
  • Currency mismatch — Fails if the input file contains more than one currency.

When the validation is complete, you receive an acknowledgment report.

Acknowledgment reports

After Payouts validates your input file, you receive one of the following acknowledgment reports:

  • ACK report — Validation passed.
  • NACK report — Validation failed.

ACK report

If your input file passes validation, Payouts places an ACK report in your Outgoing folder. The ACK report name matches the input file name, as shown in this example:

Input file name ACK report name
pp_payouts_6627887729_testfile.csv pp_payouts_6627887729_testfile_ack.csv

The file is formatted as follows:

DATE_TIME_STAMP_IN_UTC,ORIGINAL_FILE_NAME,ACCEPTED_FOR_PROCESSING

Where the date is the time of acknowledgment, as shown in this example:

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

When you receive an ACK report, Payouts begins processing the input file. You can then view reports to see the payouts status.

NACK report

If your input file fails validation, Payouts places a NACK report in your Outgoing folder. The NACK report name matches the input file name:

Input file name NACK report name
pp_payouts_6627887729_testfile.csv pp_payouts_6627887729_testfile_nack.csv

The contents of file depends on the errors that are found and follows this format:

Summary line: PAYOUT_SUMMARY,CURRENCY_CODE,ERROR_ENUM,ERROR_DESCRIPTION

Individual item records: PAYOUT,LINE_NO,REF_ID,ERROR_ENUM,ERROR_DESCRIPTION

This example shows a NACK file with errors:

PAYOUT_SUMMARY,ASD,CURRENCY_INVALID,Currency is not valid
PAYOUT_SUMMARY,USD,SUMMARY_AND_PAYOUT_MATCH_CONFLICT,Summary and Payout details must match
PAYOUT,4,fourth-ref-id,PAYOUT_AMOUNT_INVALID_FORMAT,Invalid Payout amount format

For more information on errors, see File validation errors.

Correct any issues and submit a new file with a unique name to your Incoming folder. Payouts repeats the validation and sends a new ACK or NACK report to your Outgoing folder.

When you receive an ACK report, Payouts begins processing the input file. You can then view status reports.

4. View reports

Payouts generates reports at three different file processing stages. The following table describes the reports and shows the example report name for an input file named PP_PAYOUTS_1517395059_ABC123.csv:

Report Description Example report name
Part File report Generated after a part of an input file is processed. In the case of multiple part files, the payout items are mutually exclusive across each part file. The Part file report contains the start and end row number in the file name. For example if a part file name contains 1_350, items 1 through 350 were processed. PP_PAYOUTS_1517395059_ABC123_1_350.csv
Out / Interim report Generated after all parts of an input file are processed. PP_PAYOUTS_1517395059_ABC123_OUT.csv
Final report Generated thirty-one days after the Interim report. Includes the final status of Unclaimed transactions. PP_PAYOUTS_1517395059_ABC123_FINAL.csv

Report format

The Part, Out/Interim, and Final 31-day reports all use the same format:

REF_ID,PAYOUT_ITEM_ID,TRANSACTION_ID,RECIPIENT_NAME,RECIPIENT,CURRENCY_CODE,PAYOUT_AMOUNT,FEE,TOTAL,TRANSACTION_STATUS,ERROR_ENUM,ERROR_MESSAGE,TIME_PROCESSED,TIME_CLAIMED[Applicable for Unilateral Case]

Sample report

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

Transaction status and error messages

For information on Payouts API error messages, see Payouts Error Messages.

File validation errors

The following errors may occur when Payouts validates your input file:

Error Description
SUMMARY_AND_PAYOUT_MATCH_CONFLICT The Payout amount in the Summary line doesn’t match the total item value. Please retry with the correct amount.
DUPLICATE_REF_ID Reference IDs must be unique within an input file. Please correct and retry the payout.
INVALID_REF_ID_FORMAT The Reference ID must be alphanumeric. The maximum character limit of 63. Please retry with the correct Reference ID.
PAYOUT_AMOUNT_INVALID_FORMAT The Payout amount must use a decimal. Other special characters are not allowed. Please retry with the correct format.
PAYOUT_AMOUNT_NON_POSITIVE The Payout amount must be greater than zero. Please retry with the correct amount.
SUMMARY_LINES_NON_INTEGER The total number of payments field in the Summary line must be an integer. Please retry with the correct format.
SUMMARY_LINES_NON_POSITIVE The total number of payments field in Summary line must be greater than zero. Please retry with the correct information.
SUMMARY_AMOUNT_INVALID_FORMAT The Summary amount must a decimal. Other special characters are not allowed. Please retry with the correct format.
SUMMARY_AMOUNT_NON_POSITIVE The total Payout amount in the Summary line must be greater than zero. Please retry with the correct amount.
INVALID_CURRENCY This currency is invalid. Please retry with an accepted currency format.
INVALID_FIRST_COLUMN The first column entry in the Summary must be PAYOUT_SUMMARY. For an item record, it must be PAYOUT.
MANDATORY_COLUMN_MISSING Your file is missing mandatory columns. Please enter the required info and retry the Payout.
EMAIL_SUBJECT_EXCEEDED_MAX_SIZE You’ve exceeded the maximum character limit for the email subject. The maximum length is 255.
EMAIL_MESSAGE_EXCEEDED_MAX_SIZE You’ve exceeded the maximum character limit for the email message. The maximum length is 1000.
MULTI_CURRENCY_NOT_SUPPORTED Your payout input file has more than one currency. Please retry the file with a single currency.
INVALID_FILE_NAME The format of your file name is invalid. Please retry with the correct file name.
SCHEDULED_TIME_ERROR You can schedule a payout only seven days in advance. Please retry within the seven day scheduling limit.
FILE_SIZE_ERROR Your payout input file is empty. Please retry with a valid file.
GZ_FILE_CORRUPT_ERROR Your payout input file is corrupt or has a checksum issue. Please retry with a valid file.
Feedback