Mass Payments User Guide Last updated: January 2013
Mass Payments User Guide Document Number: 10101.en_US-201301 © 2013 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.
Contents Chapter Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Chapter 1 Mass Payments Overview . .
Contents SOAP MassPay Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . 23 MassPay API Using NVP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 NVP MassPay Request Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 NVP MassPay Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 MassPay Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Chapter 4 Mass Payments Reporting . . . . . . . . . .
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.
Preface Documentation Feedback Date Published Description February 2011 Updated currency information. January 2010 New guide. Documentation Feedback Help us improve this guide by sending feedback to: documentationfeedback@paypal.
1 Mass Payments Overview “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 IM PORT AN T : Mass Payment is not enabled automatically. You must contact MTS to enable it in the Sandbox. Your account manager can arrange for it to be enabled when you are ready to go live.
1 Mass Payments Overview How Do Recipients Get Their Money? 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.
Mass Payments Overview Offering PayPal as a Payout Option On Your Site 1 have a check mailed to them, or request for PayPal to send them a debit card to access their funds. NOT E : Mass Payments User Guide All of these options are available in the U.S., but withdrawal methods vary by country.
1 10 Mass Payments Overview Offering PayPal as a Payout Option On Your Site January 2013 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.
2 Using Mass Payments in Your PayPal Account 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.
Using Mass Payments in Your PayPal Account Creating the Payment File 2 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 39. Countries with Currency Restrictions.
2 Using Mass Payments in Your PayPal Account Creating the Payment File 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 notepad, database, or a spreadsheet application like Microsoft Excel. 2. Arrange your recipient information. Let’s say you want to use Microsoft Excel to arrange your data.
Using Mass Payments in Your PayPal Account Accessing Mass Payments 2 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” on page 21. 1. Log in to your PayPal account at https://www.paypal.com. The My Account Overview page opens. NOT E : There are two versions of the PayPal web site that differ only in the way you upload, display, and research mass payment information.
2 Using Mass Payments in Your PayPal Account Uploading a Payment File 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.
Using Mass Payments in Your PayPal Account Reviewing Transaction Details 2 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.
2 Using Mass Payments in Your PayPal Account Payment Processing – Number and amounts in each of the following statuses: Claimed, Unclaimed, Denied, and Returned 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.
Using Mass Payments in Your PayPal Account Payment Processing 2 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.
2 20 Using Mass Payments in Your PayPal Account Payment Processing January 2013 Mass Payments User Guide
3 Using the Mass Payments API You can use the MassPay API to send Mass Payments. For example, you can use the MassPay API if you need to generate Mass Payments automatically, such as generating rebates every month based on information stored in a customer database. NOT E : For more information on using Mass Payments from your PayPal account, see “Using Mass Payments in Your PayPal Account” on page 11. Read the following topics to learn how to implement Mass Payments using the API.
3 Using the Mass Payments API MassPay API Using SOAP MassPay API Using SOAP For more information about the SOAP APIs, see the SOAP API Developer Reference Guide.
Using the Mass Payments API MassPay API Using NVP 3 SOAP MassPay Response Message The elements returned are the same as for AbstractResponseType. The response message follows the standard SOAP response structure. MassPay API Using NVP The following is a sample MassPay API call to two recipients using the PayPal Name-Value Pair (NVP) API. The recipients are specified by email address. USER=fictionaluser.unknowncompany.
3 Using the Mass Payments API MassPay Error Codes NVP MassPay Request Message Mass Payments Request Fields Field Description METHOD (Required) Must be MassPay. EMAILSUBJECT (Optional) The subject line of the email that PayPal sends when the transaction is completed. The subject line is the same for all recipients. Character length and limitations: 255 single-byte alphanumeric characters. CURRENCYCODE A three-character currency code. See “Currencies and Currency Codes” on page 39.
Using the Mass Payments API MassPay Error Codes Error Code Short Message Long Message 10004 Transaction refused because of an invalid argument. See additional error messages for details. The number of input records is less than or equal to zero 10004 Transaction refused because of an invalid argument. See additional error messages for details. The note string length exceeds the maximum limit of 4000 characters 10004 Transaction refused because of an invalid argument.
3 Using the Mass Payments API MassPay Error Codes Error Code 26 Short Message Long Message 10004 Transaction refused because of an invalid argument. See additional error messages for details. The transaction id is not valid 10007 Permission denied You do not have permissions to make this API call 10014 API call was rate limited. The API call has been denied as it has exceeded the permissible call rate limit.
4 Mass Payments Reporting Read the following topics to learn how to review transaction information for Mass Payments: “About Mass Payments Reporting” on page 27 “Using the Reports Dashboard to Review Mass Payment Transactions” on page 27 “Using Account History to Review Mass Payment Transactions” on page 29 “Receiving Instant Payment Notifications for Mass Payments” on page 31 “Using the Settlement Report and the Transaction Detail Report” on page 33 About Mass Payments Reporting PayPa
4 Mass Payments Reporting Using the Reports Dashboard to Review Mass Payment Transactions Searching for Mass Payments in the Report Dashboard 1. Log in to your PayPal website at https://www.paypal.com. The My Account Overview page opens. 2. Click Reports. The Reports Dashboard page opens. 3. Click Advanced Search in the Transaction finder. The Transaction finder page opens. This page contains search criteria fields to narrow your search or find a specific transaction type. 4.
Mass Payments Reporting Using Account History to Review Mass Payment Transactions 4 You can perform the following actions: Sort the transactions by Name or Gross Amount Click Print to print a copy. Click Download to save the list to a file. Downloading the Search Transaction Results 1. In the Transaction finder page, enter search criteria and click Search. 2. If you want the transactions in a different order, sort them by Name or Gross Amount. 3.
4 Mass Payments Reporting Viewing Transaction Logs 4. Click Details for the transaction to view. The Transaction Details page opens. 5. Click Return to Log to go back to the History page Using Advanced Search Use Advanced Search to find Mass Payments transactions for a specific recipient. 1. Log in to PayPal at https://www.paypal.com. The My Account Overview page opens. 2. Select Advanced Search from the History subtab. - or Click Find a transaction on the History page. The History page opens. 3.
Mass Payments Reporting Downloading History Logs 4 Downloading History Logs You can download Mass Payments information and save it on your computer using downloadable history logs. The Download History page lets you specify a time frame for payments and transactions to include in these logs. You can either download a Mass Payments transaction as a whole or download information about the individual transactions generated by the Mass Payments transaction. 1. Log in to your PayPal website at https://www.
4 Mass Payments Reporting Receiving Instant Payment Notifications for Mass Payments Processed IPN PayPal sends the Processed IPN when the payments are taken out of the payer account. For each payment, PayPal generates and returns a unique transaction ID in the masspay_txn_id variable. For each payment, PayPal also returns the unique_id value. The unique ID parameter in the MassPay API call is from your tracking system. This parameter is optional. PayPal also generates a status for each payment.
Mass Payments Reporting Using the Settlement Report and the Transaction Detail Report 4 Using the Settlement Report and the Transaction Detail Report NOT E : The Settlement and Detailed Transaction reports can be used only by approved merchants and processing partners. Contact your PayPal account manager for more information. The Settlement and Detailed Transaction reports identify different types of transactions with transaction event codes (T-codes). T-codes are five-characters long.
4 34 Mass Payments Reporting Using the Settlement Report and the Transaction Detail Report January 2013 Mass Payments User Guide
5 Best Practices and FAQs for Mass Payments Mass Payments FAQs Is there a fee to send Mass Payments? How much money can I send? What countries can receive Mass Payments? Can I send money in different currencies? How do I confirm the receipt of payments? How do I cancel an individual payment? A recipient told me that payment was not received.
5 Best Practices and FAQs for Mass Payments Mass Payments FAQs What countries can receive Mass Payments? You can send Mass Payments to the following countries: Argentina Dominican Republic India Martinique South Korea Australia Ecuador Indonesia Mexico Spain Austria Estonia Ireland Netherlands Sweden Belgium Finland Israel New Zealand Switzerland Brazil France Italy Norway Taiwan Bulgaria French Guiana Jamaica Philippines Thailand Canada Germany Japan Poland Turkey Chile
Best Practices and FAQs for Mass Payments Mass Payments FAQs 5 How do I confirm the receipt of payments? PayPal will send you a notification email once the Mass Payments request has completed. You can then log in to your PayPal account and review the details of each transaction. There are two ways to check the status of your payments: Complete Summary of One Mass Payment 1. Log in to your PayPal account and view your recent activity. 2. Click Details next to your Mass Payments transaction. 3.
5 Best Practices and FAQs for Mass Payments Mass Payments FAQs Recipient has an unconfirmed email address Your recipient cannot receive a payment with an unconfirmed email address. Ask your recipient to confirm the email address with PayPal. Once that’s done, the payment should appear in the recipient’s PayPal account in a few minutes. Recipient did not receive the payment email Sometimes PayPal emails get redirected to a recipient’s spam folder.
A Currencies and Currency Codes PayPal uses 3-character ISO-4217 codes for specifying currencies in fields and variables. Currencies and Currency Codes Supported by PayPal Currency Currency Code Australian Dollar AUD Brazilian Real BRL N O TE : This currency is supported as a payment currency and a currency balance for in-country PayPal accounts only.
A Currencies and Currency Codes Currency Currency Code Swiss Franc CHF Taiwan New Dollar TWD N O TE : This currency does not support decimals. Decimal amounts will throw an error. Thai Baht THB Turkish Lira TRY N O TE : This currency is supported as a payment currency and a currency balance for in-country PayPal accounts only. U.S.
