<< Mass Payments Overview

Using Mass Payments in Your PayPal Account

You can submit Mass Payments directly from your PayPal account or use the MassPay API to submit them.

Read the following topics to learn about using Mass Payments in your PayPal account:

The Mass Payments Process

In general, you complete the following steps to send Mass Payments from your PayPal account:

  1. Collect recipient information and create a payment file. See Creating the Payment File.
  2. Access Mass Payments in your PayPal account. See Accessing Mass Payments.
  3. Upload your payment file. See Uploading a Payment File.

Creating the Payment File

You must create a payment file to send Mass Payments. A payment file contains recipient and payment information. Mass Payments lets you send up to 5,000 payments in one batch.

You can create a payment file using a notepad application, a spreadsheet application such as Microsoft Excel, or a database application. PayPal supports payment files with the following extensions:

  • .TXT (Text, tab-delimited)
  • .CSV (Comma Separated Value)
  • .DAT (Text, tab-delimited)

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.

For a description of the fields you can include, see Payment File Contents. For instructions on preparing the payment file, see Preparing the Payment File.

Payment File Contents

The payment file contains the following information:

Table 1. Payment File Contents
Item Description
Recipient

(Required)
Unique identifier for the recipient, one of the following:

  • Email address
  • PayPal account ID (PayPal PayerID)
    If you are using Mass Payments in conjunction with Express Checkout or with the Account Authentication Service, the PayPal PayerID is returned.
  • Telephone number
    The telephone number is the user's mobile number.

Note Payments in the same payment file must use the same type of recipient identifier. For example, you cannot provide an email address for some recipients and a telephone number for other recipients in the same payment file.

Payment Amount (Required)
Amount of the recipient's payment.

Note The Masspay UI supports the currency format specific to 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 (Required)
Three-letter currency code.

Note Payments in different currencies must have separate payment files.

For a list of the valid codes, see Currencies and Currency Codes.

Customer ID (Optional)
Unique identifier. It has a 30-character maximum and cannot contain any spaces.
Custom Note (Optional)
A unique sender defined message. When provided, this customized message is only sent to the individual recipient.

You can have only one recipient type and one currency type per payment file. If you need to send Mass Payments to some recipients with email addresses and some with PayPal account IDs, you must create separate payment files for each type. If you need to send Mass Payments with multiple currency types, you must create separate payment files for each currency.

Currency Types

You can have only one currency type per payment file. 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.

For a complete list of the currency codes, see Currencies and Currency Codes.

Countries with Currency Restrictions

If you are a PayPal account holder in a country with currency restrictions, make sure that your Mass Payment payment file contains requests that meet your country's requirements. If any of the payment file entries do not comply with the country's restrictions, those entries will fail with an error message. The remaining payment file entries will be processed, assuming that there are no other errors in the file.

The following table lists the countries with currency restrictions and describes the restrictions that apply to 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 cannot:

  • 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 can:

  • Send payments in BRL only to other Brazilian users.
  • Send payments in other currencies only to those outside Brazil.

Brazilian users cannot:

  • Send payments to other Brazilian users in a currency other than BRL.
  • Send payments that result in currency conversion to or from BRL.

Note Non-Brazilian users cannot hold currency balances in BRL.

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

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

Preparing the Payment File

Before starting, collect your recipient information. 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 the Notepad application, a database, 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.
    • 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 or for adding a note to the recipient.

    Example:

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

    Recipient ID Payment Currency Customer ID Note
    mbrown@mycompany.com 10.00 USD ID001 Thanks for your business!

    Note Some countries have restrictions on sending and receiving 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 Text (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 a Text (tab-delimited) file:
name1@email.com   10.00   USD   masspay_001   Thanks for your business!
name2@email.com   10.00   USD   masspay_002   Here is your payment.
name3@email.com   10.00   USD   masspay_003
name4@email.com   10.00   USD   masspay_004
name5@email.com   10.00   USD   masspay_005

Note You can have only one recipient identifier type (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.

Accessing Mass Payments

You can access Mass Payments through your PayPal account or through the PayPal API. For information about using the MassPay API, see Using the Mass Payments API.

  1. Log in to your PayPal account at https://www.paypal.com.
    The My Account Overview page opens.

    Note There are two versions of the PayPal web site that differ only in the way you upload, display, and research mass payment information. The instructions for uploading files are slightly different in each version.
    To determine which instructions to use, look at the subtab area of the My Account Overview page.
    If the Reports subtab is present, see Uploading the Mass Payments File (Reports Subtab Present) uploading instructions.
    If the Reports subtab is not present, see Uploading the Mass Payments File (No Reports Subtab) for uploading instructions.

  2. Click the Send Money tab.
    The Send Money Online page opens.
  3. Click the Make a Mass Payment subtab.
    The Mass Payment page opens.

You can now upload your Mass Payments file.

Uploading a Payment File

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

  • Your Mass Payments file is a .TXT, .CSV, or .DAT 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.

    Note Your PayPal balance must be in the same currency as your Mass Payments request.

Uploading the Mass Payments File (Reports Subtab Present)

Use these instructions if Reports appears in the subtab area of the My Account Overview page. If Reports is not present, see Uploading the Mass Payments File (No Reports Subtab) for uploading instructions.

  1. Open the Mass Payment page.
  2. Choose a category in the My recipients are identified by field that matches type of recipient ID you used. Choose Email address, Phone number, or PayPal customer ID.
  3. (Optional) Customize the Mass Payments email message by entering text in the Email subject field and the Message to Recipient text box.
  4. Click Upload.
    In the Open dialog box, select your payment file and click Open.
  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 and 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 area.
    To edit the Mass Payments email message, click Make Changes. The Mass Payment page opens letting you make changes to the Mass Payments request.
  7. Click Submit to start the Mass Payments processing.
    The Mass Payment page displays the 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
    • View the details of the Mass Payments transaction
    • Submit another Mass Payments request
    • Go to your Account Overview

Uploading the Mass Payments File (No Reports Subtab)

Use these instructions if you do not see Reports in the subtab area of the My Account Overview page. If Reports is present, see Uploading the Mass Payments File (Reports Subtab Present) for uploading instructions.

  1. Open the Mass Payment page.
  2. Enter the pathname for your payment file in the Attach Mass Payment File field, or click Browse to locate the file on your computer.
  3. Choose the category in the Recipient Type field that matches the type of recipient ID you used. Choose Email address, Phone Number, or User ID.
  4. (Optional) Customize the Mass Payments email message by entering text in the Email Subject field and the Note text box.
  5. Click Continue.
    PayPal scans your payment file for errors. If the file is valid, the Mass Payment page displays the We've successfully read your file message, a summary of the mass payment information, and the associated fees.
  6. Review the displayed information. If it is correct, click Send Money.
    The You have sent a payment page opens after PayPal processes the transactions. From this page, you can click links to
    • View the details of the Mass Payments transaction
    • Submit another Mass Payments request
    • Go to your Account Overview

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

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 the release, if one or more transactions is declined, your PayPal account balance may exceed the available account balance shown during the period of the hold.

Reviewing Transaction Details (Reports Subtab Present)

  1. On the final Mass Payment page (displays the Thank you. Your Mass Payment has been submitted message), click the View the details of this Mass Payment link.
    The Transaction Details page opens
  2. The Transaction Details page opens and displays summary information about the Mass Payments transaction, including:
    • Transaction ID
    • Date and time processed
    • Number of individual payments
    • Payment source
    • Number and amounts in each of the following statuses: Claimed, Unclaimed, Denied, Returned, Pending, and Blocked. See status descriptions for details.
    This page also includes a link you can use to search for a recipient if you need to cancel the payment and a link to download the payment file to review.
  3. Click the Go to Account overview link to go to your Account Overview page.

Reviewing Transaction Details (No Reports Subtab)

  1. On the You have sent a payment page, click View the details of this transaction.
  2. The Transaction Details page opens and displays summary information about the Mass Payments transaction, including
    • Date and time submitted
    • Date and time processed
    • Number of payments: Total, Claimed, Unclaimed, Denied, Returned, Pending, and Blocked. See status descriptions for details.
    • Processing status: Processing, Denied, Processed, or Completed. See the FAQs for more information.
    • Payment amount
    • Fee amount
    • Mass Payments total
    • Funding source
  3. You can get additional information by clicking the See Details button to download the Batch log. For information about the Batch log, see Downloading History Logs.
  4. Click Return to Log to see your Account History.

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.

  • 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 recepient will recieve a text message from PayPal.
  • 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 recepient will sent a text messages directing them to collect the payment. The mobile number is then added to their PayPal account.
  • If the recipients do not have a PayPal account, their email message contains a link that directs them to a PayPal sign-up page. The sign-up process automatically confirms their email address. When they complete the sign-up 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 will be updated within 72 hours.
Blocked: This payment was blocked due to a violation of government regulations.

Using the Mass Payments API >>