Large Batch Payouts

Large Batch Payouts enables you to send payouts to an unlimited amount of recipients at once. To use Large Batch Payouts, create a payouts input file and place it in a folder on a secure FTP server.

How it works

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

Before you begin, complete the prerequisites.

1. Set up 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 this 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 include this 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

Transactions performed in the production environment are live. Money is debited from your PayPal balance and credited to each recipient. If the recipient doesn't claim the money within 30 days from the payout date, the money is returned to your account.

To set up your production environment:

1. Contact your account manager or PayPal customer support and provide this 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 include this 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 input file

Create a comma separated value (.csv) input file that includes a summary line and information for each individual payout item.

The following sample .csv sends a payout to two recipients to select their payout method, two PayPal recipients and two Venmo recipients:

1PAYOUT_SUMMARY,17.9,USD,5,"You got paid",Payout for
2PAYOUT_RECIPIENT_SELECTED,test-1paypal.com,5.24,USD,REF_ID_1,NOTE_1
3PAYOUT_RECIPIENT_SELECTED,test-2paypal.com,10.85,USD,REF_ID_2,NOTE_2
4PAYOUT,test-5@paypal.com,3.51,USD,REF_ID_3,NOTE_3
5PAYOUT,test-6paypal.com,1.87,USD,REF_ID_4,NOTE_4
6PAYOUT_VENMO,5551232368,4.93,USD,REF_ID_5,NOTE_5
7PAYOUT_VENMO,5551232369,2.77,USD,REF_ID_6,NOTE_6

Add Summary line

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

1PAYOUT_SUMMARY,TOTAL_PAYOUT_AMOUNT,CURRENCY_CODE,TOTAL_NO_OF_PAYMENTS,EMAIL_SUBJECT,EMAIL_MESSAGE

Use this information to complete each field of the summary:

• Static value.
• Must be upper case.

| | `TOTAL_PAYOUT_AMOUNT` |

• Value of all individual payout items.
• Must be in decimal format.

| | `CURRENCY_CODE` |

• [Currency](/limited-release/payouts/reference/country-and-currency-codes/) for the payout, such as `USD`, `EUR`, and so on. Only one currency type is supported per input file.

| | `TOTAL_NO_OF_PAYMENTS` |

• The 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.
• For `txt` input files:
  • If an email subject contains a comma or other special character, enclose the subject in double quotes.
  • If an email subject contains a double quote, enclose the double quote with an additional set of double quotes and enclose the subject in double quotes. Example double quote subject: `"Our way of saying ""thanks"""`
• Max character length: 256

| | `EMAIL_MESSAGE` |

• A common note in the email notification sent to all recipients for all payout items.
• For `txt` input files:
  • If a note contains a comma or other special character, enclose the note in double quotes.
  • If a note contains a double quote, enclose the double quote with an additional set of double quotes and enclose the entire note with double quotes. Example double quote note: `"Our way of saying ""thanks"""`
• Max character length: 1000

|

Add individual item records

Beginning with the second line of the input file, add a record for each individual payout item as shown in this example:

1PAYOUT,RECIPIENT,PAYOUT_AMOUNT,CURRENCY_CODE,UNIQUE_REF_ID, ITEM_LEVEL_NOTE

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

• Set to `PAYOUT_RECIPIENT_SELECTED` to allow recipient to choose payment method
• Set to `PAYOUT` for a PayPal recipient
• Set to `PAYOUT_VENMO` for a Venmo recipient
• Must be upper case.

| `RECIPIENT` |

• The recipient identifier.
• Use the recipient's email address, phone number, 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:
  • If a note contains a comma or other special character, enclose the note in double quotes.
  • If the note contains a double quote, enclose the double quote with an additional set of double quotes and enclose the entire note with double quotes. Example double quote note: `"Our way of saying ""thanks"""`
• Maximum character length: 1000

Save input file

Use this naming convention to save the file:

1pp_payouts_<epoch_time>_<reference_name><format>

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

3. Upload input file

You can upload and test your input file in your sandbox environment or upload your input file to your production environment 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 doesn't 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 doesn't match the payout item record details.
• Duplicate file validation — Fails if the input file name isn't unique. The file can't 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 these 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:

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 payout 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:

The file contains the errors found and is formatted as follows:

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:

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

For more information on errors, see File validation errors.

Correct any issues. Give the corrected file a unique name and put it in your Incoming folder. Payouts validates again 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. This table describes the reports and shows the example report name for an input file named PP_PAYOUTS_1517395059_ABC123.csv:

Report format

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

1REF_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

1REF_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
2REF_ID_2,HP3B9BRJYMKRU,1H080416VK328525U,,bjonny-us4@paypal.com,USD,4.93,0.25,5.18,SUCCESS,,,2018-01-16T10:33:20Z
3REF_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
4REF_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
5REF_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

These errors may occur when Payouts validates your input file. Once you've fixed the errors, retry the payout:

Next

Add payouts features.