PayPal Mass Payment - 2012 User Guide
Mass Payments User
Guide
Last updated: February 2012
Mass Payments User Guide
Document Number: 10101.en_US-201202
© 2012 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other
trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.
Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L2449, Luxembourg, R.C.S. Luxembourg B 118 349
Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval
of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.
Notice of non-liability:
PayPal, Inc. is providing the information i n this document t o you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information co ntained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting f rom the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Chapter 1 Mass Payments Overview . . . . . . . . . . . . . . . . . . 7
What is Mass Payments? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Mass Payments Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
How Do Recipients Get Their Money?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Who Can Use Mass Payments? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Offering PayPal as a Payout Option On Your Site . . . . . . . . . . . . . . . . . . . . . . . 8
Chapter 2 Using Mass Payments in Your PayPal Account . . . . . . .11
The Mass Payments Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Creating the Payment File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Payment File Contents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Preparing the Payment File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Accessing Mass Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Uploading a Payment File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Uploading the Mass Payments File (Reports Subtab Present) . . . . . . . . . . . . . 15
Uploading the Mass Payments File (No Reports Subt ab) . . . . . . . . . . . . . . . . 16
Reviewing Transaction Details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Reviewing Transaction Details (Reports Subtab Present). . . . . . . . . . . . . . . . 17
Reviewing Transaction Details (No Reports Subtab) . . . . . . . . . . . . . . . . . . 18
Payment Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Chapter 3 Using the Mass Payments API . . . . . . . . . . . . . . . .21
Calling the MassPay API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
MassPay API Using SOAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
SOAP MassPay Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Mass Payments User Guide February 2012 3
Contents
SOAP MassPay Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . 23
MassPay API Using NVP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
NVP MassPay Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
NVP MassPay Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
MassPay Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Chapter 4 Mass Payments Reporting . . . . . . . . . . . . . . . . . .29
About Mass Payments Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Using the Reports Dashboard to Review Mass Payment Transactions . . . . . . . . . . . 29
Searching for Mass Payments in the Report Dashboard . . . . . . . . . . . . . . . . 30
Using the Search Transaction Results List . . . . . . . . . . . . . . . . . . . . . . . 30
Downloading the Search Transaction Results. . . . . . . . . . . . . . . . . . . . . . 31
Using Account History to Review Mass Payment Transactions . . . . . . . . . . . . . . . 31
Viewing Transaction Details Using Basic Search . . . . . . . . . . . . . . . . . . . . 31
Using Advanced Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Viewing Transaction Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Downloading History Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Receiving Instant Payment Notifications for Mass Payments . . . . . . . . . . . . . . . . 33
Processed IPN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Using the Settlement Report and the Transaction Detail Report. . . . . . . . . . . . . . . 35
About Mass Payments and the Settlement Report . . . . . . . . . . . . . . . . . . . 35
About Mass Payments and the Transaction Detail Report . . . . . . . . . . . . . . . 35
Chapter 5 Best Practices and FAQs for Mass P ayments . . . . . . . .37
Mass Payments FAQs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Is there a fee to send Mass Payments? . . . . . . . . . . . . . . . . . . . . . . . . . 37
How much money can I send?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
What countries can receive Mass Payments?. . . . . . . . . . . . . . . . . . . . . . 38
Can I send money in different currencies? . . . . . . . . . . . . . . . . . . . . . . . 38
How do I confirm the receipt of payments? . . . . . . . . . . . . . . . . . . . . . . . 38
How do I cancel an individual payment?. . . . . . . . . . . . . . . . . . . . . . . . . 39
A recipient told me that payment was not received. What could be the problem? . . . 39
What does it mean if a mass payment is “Processing, Denied, Processed or Completed” in
my transaction history? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Appendix A Currencies and Currency Codes . . . . . . . . . . . . . . 41
4 February 2012 Mass Payments User Guide
Preface
About This Guide
The Mass Payments User Guide describes how to use the PayPal website and the MassPay
API to send Mass Payments, to search for Mass Payment transactions, and to view summary
and detailed Mass Payment information.
The following table summarizes the contents of this guide.
Feature See
Frequently asked questions “Mass Payments FAQs” on page 37
MassPay errors “MassPay Error Codes” on page 25
NVP API “MassPay API Using NVP” on page 23
Reporting “Mass Payments Reporting” on page 29
Sending Mass Payments from the PayPal site “Using Mass Payments in Your PayPal Account” on page 11
SOAP API “MassPay API Using SOAP” on page 22
Intended Audience
This guide is for merchants and secondary users who log in to PayPal accounts for a variety of
set-up and administrative tasks.
Revision History
The following table lists the revisions made to the Mass Payments User Guide.
Date Published Description
February 2012 Maintenance release.
February 2011 Updated currency information.
January 2010 New guide.
Mass Payments User Guide February 2012 5
Documentation Feedback
Documentation Feedback
Help us improve this guide by sending feedback to:
documentationfeedback@paypal.com
6 February 2012 Mass Payments User Guide
Mass Payments Overview
1
“What is Mass Payments?” on page 7
“Mass Payments Processing” on page 7
“How Do Recipients Get Their Money?” on page 8
“Who Can Use Mass Payments?” on page 8
“Offering PayPal as a Payout Option On Your Site” on page 8
IMPORTANT: Mass Payment is not enabled automatically. You must contact MTS to enable
it in the Sandbox. Y our account manager can arrange for it to be enabled when
you are ready to go live.
What is Mass Payments?
Mass Payments lets you send multiple payments in one batch. It's a fast and convenient way to
send commissions, rebates, rewards, and general payments. You must have explicit permisson
from PayPal to use Mass Payments.
You submit the payment information to PayPal in the form of a payment file. PayPal processes
each payment and notifies you when it is complete.
There are two ways to send your payment information:
1. Upload a payment file directly to the PayPal site.
For instructions, see “Using Mass Payments in Your PayPal Account” on page 11.
2. Submit the information through APIs.
For instructions, see “Using the Mass Payments API” on page 21.
Mass Payments Processing
When a Mass Payments request is executed, PayPal processes each payment in the request.
PayPal takes the payment amounts from your account and attempts to put them into the
recipients’ PayPal account. If the recipients do not have PayPal accounts, PayPal notifies them
that a payment is available and they must create a PayPal account to receive the payment.
Payments processing can take from a couple of minutes to several hours, depending on the
number of payments you are processing.
Mass Payments User Guide February 2012 7
Mass Payments Overview
1
How Do Recipients Get Their Money?
When the payments have been sent, PayPal sends you a notification email. You can then log in
to your PayPal account and get the details of each transaction.
PayPal holds the mass payment amounts for 30 days. If a payment is unclaimed after 30 days,
the money is returned to your account.
How Do Recipients Get Their Money?
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 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 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.
Who Can Use Mass Payments?
You must have a PayPal Premier account or Business account, and it must be a verified
account, before you can use Mass Payments. If you have multiple users for your PayPal
account, you can grant access to one or more authorized users to have them send Mass
Payments for you. For example, you can grant Mass Payments access to your bookkeeper or to
your customer service agents as part of their duties.
IMPORTANT: Mass Payment is not enabled automatically. You must contact MTS to enable
it in the Sandbox. Y our account manager can arrange for it to be enabled when
you are ready to go live.
Offering PayPal as a Payout Option On Your Site
To offer PayPal as a payout option to your customers, you only need to ask for their email
address. If they have a PayPal account, they should provide the email address that they use
with their PayPal account. If they don’t have a PayPal account, they will be asked to sign up
for one when they receive their payment notice.
8 February 2012 Mass Payments User Guide
Mass Payments Overview
Offering PayPal as a Payout Option On Your Site
Let your customers know they will receive an email from PayPal when their payment has been
sent. This email contains instructions on how to access their money. Your customers will then
have the option to make online purchases with their money, withdraw it to a bank account,
have a check mailed to them, or request for PayPal to send the m a debit card to access their
funds.
NOTE: All of these options are available in the U.S., but withdrawal methods vary by country .
1
Mass Payments User Guide February 2012 9
Mass Payments Overview
1
Offering PayPal as a Payout Option On Your Site
10 February 2012 Mass Payments User Guide
2
Using Mass Payments in Your PayPal Account
You can submit Mass Payments directly from your PayPal account or use the PayPal API to
submit them.
Read the following topics to learn about using Mass Payments in your PayPal account:
“The Mass Payments Process” on page 11
“Creating the Payment File” on page 11
“Accessing Mass Payments” on page 15
“Uploading a Payment File” on page 15
“Payment Processing” on page 18
For information about using the MassPay API, see “Using the Mass Payments API” on
page 21.
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”
on page 11.
2. Access Mass Payments in your PayPal account. See “Accessing Mass Payments” on
page 15.
3. Upload your payment file. See “Uploading a Payment File” on page 15.
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)
Mass Payments User Guide February 2012 11
Using Mass Payments in Your PayPal Account
2
Creating the Payment File
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” on page 12. For
instructions on preparing the payment file, see “Preparing the Payment File” on page 14.
Payment File Contents
The payment file contains the following information:
Payment File Contents
Item Description
Recipient (Required)
Unique identifier for the recipient, one of the following:
Email address
PayPal account ID
If you are using Mass Payments in conjunction with Express Checkout or the
Authorization API., the PayPal ID is returned.
Telephone number
The telephone number is the user’s mobile number.
Payment Amount (Required)
Amount of the recipient’s paymen t.
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” on page 41.
Customer ID (Optional)
Unique identifier. It has a 30-character maximum and cannot contain any spaces.
Custom Note (Optional)
Additional information to the customer.
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
12 February 2012 Mass Payments User Guide
Using Mass Payments in Your PayPal Account
of your Mass Payment request will fail and you will get an error message describing the issue.
See “Countries with Currency Restrictions” on page 13 for information about the countries
with restrictions.
For a complete list of the currency codes, see “Currencies and Currency Codes” on page 41.
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 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 Ar gentina
Send payments that result in currency conversion to or from ARS.
NOTE: Non-Argentine users cannot hold currency balances in ARS.
Creating the Payment File
2
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.
Mass Payments User Guide February 2012 13
Loading...