Use Mass Payments in Your PayPal Account

Note: The MassPay API is Deprecated as of September 1, 2017. For new integrations, see the Payouts Overview.

You can submit Mass Payments directly from your PayPal account on or programmatically submit them using the MassPay API.

The Mass Payments process

Complete the following steps to send Mass Payments from your PayPal account:

  1. Create the payment file
  2. Access Mass Payments
  3. Upload a payment file
  4. Review transaction details

Create the payment file

First, create a payment file containing the Mass Payments details. A payment file includes recipient and payment information. Mass Payments lets you send up to 5,000 payments in one file.

You can create a payment file using a basic text editor application, such as NotePad or TextEdit, a spreadsheet application such as Microsoft Excel, or a database application. PayPal supports mass payment files with the following extensions: .TXT (text, tab-delimited) or .CSV (comma separated value).

Each line in the payment file represents one recipient and at minimum must contain the recipient's identification, the amount to pay, and the currency type. You can also provide custom information, if necessary.

Payment file contents

The payment file includes the following information:

Item Description
Recipient (Req) Unique identifier for the recipient, one of the following: email address, PayPal PayerID, or mobile telephone number. If you are using Mass Payments in conjunction with Express Checkout or with the Account Authentication Service, these APIs return the PayPal PayerID in the transaction's response message.
Note: Payments in the same payment file must use the same type of recipient identifier. For example, you cannot provide only an email address for some recipients and only a telephone number for other recipients in the same payment file.
Payment Amount (Req) Amount of the recipient's payment
Note: Mass Payments supports the currency amount formatted specific to your (the sender's) country. A sender in Italy should enter the amount with a comma as the decimal separator (e.g. 5,45), and a sender in the US should enter the amount with a period as the decimal separator (e.g. 5.45).
Currency Type (Req) Three-letter currency code. For a list of the valid codes, see Currencies and Currency Codes.
Note: You can have only one currency type per payment file. Payments in different currencies must have separate payment files.
Currency type codes are not case sensitive. For example, both usd and USD codes are acceptable for U.S. Dollars.

In general, you can send Mass Payments using most currencies. However, there are a few countries that place limitations on how their currency can be used or exchanged. If your Mass Payment request does not comply with the currency restrictions of your country, that portion of your Mass Payment request will fail, and you will get an error message describing the issue. See Countries with Currency Restrictions for information about the countries with restrictions.
Customer ID (Opt) Unique identifier. It has a 30-character maximum and cannot contain any spaces.
Custom Note (Opt) A unique sender defined message. When provided, this customized message is only sent to the individual recipient.

Countries with Currency Restrictions

If you are a PayPal account holder in a country with currency restrictions, make sure that your Adaptive Payment code or Mass Pay file contains requests that meet your country's requirements. If any of the Mass Pay entries do not comply with the country's restrictions, those entries will fail with an error message.

The following table lists the countries with currency restrictions and describes the restrictions that apply to Adaptive Payments and Mass Payments.

Country Currency Code Restrictions
Argentina ARS

Argentine users can:

  • Send payments in ARS only to other Argentine users.
  • Send payments in other currencies to all users, including those in Argentina.

Argentine users can't:

  • Send payments in ARS to users outside of Argentina.
  • Send payments that result in currency conversion to or from ARS.

    Note: Non-Argentine users cannot hold currency balances in ARS.

Brazil BRL

Brazilian users:

This currency is supported as a payment currency and a currency balance for in-country PayPal accounts only. If the receiver of funds is not from Brazil, then PayPal converts funds into the primary holding currency of the account with the applicable currency conversion rate. The currency conversion rate includes PayPal's applicable spread or fee.

Malaysia MYR

Malaysian users can:

  • Send payments in MYR only to other Malaysian users.
  • Send payments in other currencies to all users, including those in Malaysia.

Malaysian users can't:

  • Send payments that result in currency conversion to or from MYR.
  • Send MYR balances to non-Malaysian users.

    Note: Non-Malaysian users cannot hold currency balances in MYR.

Prepare the payment file

Collect your recipient information, then use the following instructions to create a Mass Payments file.

  1. Choose how you will generate the payment file. You can use a plain text editor, such as Notepad or TextEdit, a database application, or a spreadsheet application like Microsoft Excel.
  2. Arrange your recipient information. For example, if you are using Microsoft Excel to arrange your data, the file formatting guidelines are:

    • Each row in your spreadsheet should contain the data for one recipient, divided into five columns.
    • Optionally, the first row in the Mass Payments file can be treated as a header row.
    • From left to right, enter the recipient's identifier (such as an email address), the payment amount, and the 3-letter currency code.
    • The first three columns are required. The fourth and fifth columns are optional and can be used for your internal tracking purposes or for adding a customized note to the recipient.

    Here's an example of how the data could be arranged.

    Recipient ID Payment Currency Customer ID Note 10.00 USD ID001 Thanks for your business!

    Note: Some countries have restrictions on sending and receiving payments in their currency. If your payment file entries do not fall within those restrictions, you will get an error message. See Countries with Currency Restrictions for a description of those limitations.

  3. Generate the file. For example, to generate a Mass Payments file from Excel, save the file as .txt (tab-delimited) or .csv (comma delimited). If you are using a different software application, make sure the program you are using allows you to save in the tab-delimited format. Here is an example of the contents of a tab-delimited text (.txt) file:  10.00   USD   ID001   Thanks for your business!   10.00   USD   ID002   Here is your payment.   10.00   USD   ID003   10.00   USD   ID004   10.00   USD   ID005

    Note: You can have only one recipient identifier type (either email address, PayPal PayerID, or phone number) and one currency type in a payment file. If you need to send payments to different recipient types or multiple currencies, you must create separate payment files.

Access mass payments

You can access the Mass Payments submission page in your PayPal account on

Note: You can also use the MassPay API to programmatically generate and send mass payments. For information, see Using the Mass Payments API.

  1. Log in to your PayPal account at
  2. Your account Summary page opens.
  3. Click Money at the top and then Send Money on the left.
  4. Click Make a Mass Payment. The Mass Payment page opens.

You can now upload your Mass Payments file.

Upload a payment file

Before uploading your payment file, make sure to check the following:

  • Your Mass Payments file is a .TXT or .CSV file and it contains only one currency type and only one recipient identifier type.
  • Your PayPal account contains enough funds to cover the total cost of the Mass Payments request. You can use only money from your PayPal balance for Mass Payments.
  • Your PayPal balance must be in the same currency as your Mass Payments request.

To upload a payment file:

  1. Access mass payments.
  2. Click Upload. Then, in the file open dialog box, select your payment file and click Open.
  3. Choose a category from the My recipients are identified by drop down menu that matches the type of recipient ID you used. Choose from Email address, Phone number, or PayPal customer ID.
  4. Optionally, you can customize a Mass Payment email message sent to all recipients by entering text in the Email subject field and in the Custom message for recipient text box.
  5. Click Review. PayPal scans your payment file for errors. If the file is valid, the Mass Payment page displays the Review and send payment information with the associated fees.
  6. Review the displayed information. You can also preview the email message that the recipients receive by clicking Preview in the Email to recipient section. To edit the Mass Payments email message, click Make Changes. The Mass Payment page opens letting you make changes to your Mass Payments request.
  7. Click Submit to start processing your Mass Payment. The Mass Payment page displays a Thank you. Your Mass Payment has been submitted message. PayPal notifies you when the payments have been sent. From this page, you can click links to the following:

    • View the details of the Mass Payments transaction. See Viewing transaction details for more information.
    • Submit another Mass Payments request.
    • Return to your account Account overview (Summary) page.

Review transaction details

You can review your Mass Payments transaction details immediately after it has been submitted. The last page in the Mass Payments process includes a link to access the information. You can also access details about a mass payment in the Recent activity section of your account Summary (or Overview) page as well as from your account Activity (or History) page.

If the status of the transaction still shows as Submitted, you need to wait for the status to change to Processed or Completed to see the number of unclaimed payments. Give the process additional time, and check back later.

PayPal will place a temporary hold on the total monetary value of the Mass Payment, plus associated fees, until the status of the transaction is changed to Processed. After releasing the temporary hold, if one or more transactions is declined, your PayPal account balance may exceed the available account balance shown during the period of the hold.

View transaction details

  1. From the mass payment confirmation page, select View the details of this transaction. You can also view the details of a mass payment from the Recent activity section of your account Summary (or Overview) page as well as from your account Activity (or History) page.
  2. The Transaction Details page opens and displays summary information about the Mass Payments transaction, including

    • Date and time submitted
    • Date and time processed
    • Total number of payments
    • Processing status of the entire mass payment: Processing, Denied, Processed, or Completed. See the FAQs for more information.
    • A table detailing the processing status of the payments grouped into the following categories: Claimed, Unclaimed, Denied, Returned, Pending, and Blocked. Place your mouse cursor over each of these status names on this page for a description or see status descriptions for details.
  3. To cancel an unclaimed payment, click by email address or name to search for the payment.
  4. You can also get additional information by clicking the Download Log button / drop down menu to download the Batch log in either the .txt or .csv file formats. For information about the Batch log, see Downloading History Logs.

Payment processing

When a Mass Payments request is executed, PayPal processes each payment in your Mass Payments file. PayPal takes the payment amounts from your account and attempts to put them into the recipients' PayPal accounts. PayPal notifies recipients without a PayPal account by email that a payment is available and they must claim it. If a payment is unclaimed after 30 days, the money is returned to your account.

When the payments have been sent, PayPal sends you a summary email for each Mass Payment. You can then log in to your PayPal account and get the details of each transaction.

Every recipient receives an email notifying them of the payment. There are three scenarios for recipients.

  1. Recipients with a PayPal account tied to the email address that contains the payment notification can click a link in the email message, log in to their account, and access their payments. If a payment is sent to a mobile number, the recipient will receive a text message from PayPal.
  2. If the recipients have a PayPal account, but the payment is sent to an email address that is not tied to their account, they are offered an opportunity to log in to their account. Then, when they log in, the money is deposited to their account and the new email address is added to their account automatically. If the payment is sent to a mobile number not associated with a PayPal account, the recipient is sent a text message describing how to collect the payment. The mobile number is then added to the recipient's PayPal account.
  3. If the recipients do not have a PayPal account, their email message contains a link that directs them to a PayPal signup page. The signup process automatically confirms their email address. When they complete the signup process, the money is available in their new PayPal account. If the payment is sent to a mobile number and the recipient has no PayPal account, a link in the text message will allow the recipient to sign up for a PayPal account.

Status descriptions

The status of individual records in a Mass Payment could be one of the following:

  • Claimed — The payment has been processed, regardless of whether this was originally a unilateral payment.
  • Denied — The payment failed because of an insufficient PayPal balance.
  • Returned — Payment has been returned after 30 days.
  • Unclaimed — This is for unilateral payments that are unclaimed.
  • Pending — The payment is pending because it is being reviewed for compliance with government regulations. The review will be completed and the payment status updates within 72 hours.
  • Blocked — This payment was blocked due to a violation of government regulations.


Incorrect email address

If the recipient's email address was entered incorrectly, you'll need to resend their payment.

  1. Log in to your PayPal business account and make sure you have enough money in your PayPal balance to cover the total cost of the payout.
  2. Create a .CSV or .TXT file with the recipient's corrected email address, payment amount, and currency type.
  3. Upload and submit your payout.

Unconfirmed email address

Your recipient cannot receive a payment with an unconfirmed email address. You'll need to ask the recipient to confirm their email address with PayPal. Once they've confirmed, the payment should appear in their PayPal account in a few minutes.

Recipient did not receive the email

If you suspect the email may have been redirected to a recipient's spam folder, ask your recipient to log in to their PayPal account to view the payment.

Reverse payments

PayPal is unable to reverse funds for any incorrect reverse funds for any incorrect recipient email addresses or mobile phone numbers included in an uploaded file unless the money is unclaimed after 30 days.

Unclaimed payments

If money is not claimed within 30 days, PayPal will return the money to your PayPal account. Go to your transaction history to view any unclaimed payments.


Use the Mass Payments API