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.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . .
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.
Documentation Feedback 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? 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.
Mass Payments Overview Offering PayPal as a Payout Option On Your Site 1 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 them a debit card to access their funds.
1 10 Mass Payments Overview Offering PayPal as a Payout Option On Your Site 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.
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 41. 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 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.
2 20 Using Mass Payments in Your PayPal Account Payment Processing February 2012 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 Request Fields Field Description EmailSubject xs:string (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. MassPayItem ebl:MassPayItemType (Required) Details of each payment. NOTE: ReceiverType A single MassPayRequest can include up to 250 MassPayItems.
3 Using the Mass Payments API MassPay API Using NVP USER=fictionaluser.unknowncompany.com& PWD=apiPassword& SIGNATURE=AFcFxV21C7fd0v3bYYYRCpSSRl31ACInnLACIHV5EdPnjIVOlb1a6kn9& VERSION=2.3& METHOD=MassPay& RECEIVERTYPE=EmailAddress& L_EMAIL0=fred@unknowncompany.com& L_AMT0=25.99& L_EMAIL1=john@fictionalcompany.com& L_AMT1=9.99& CURRENCYCODE=USD NOT E : Carriage returns have been added to the code example for easier reading.
Using the Mass Payments API MassPay Error Codes 3 MassPay Error Codes MassPay API Errors Error Code Short Message Long Message 10001 Invalid account number. The transaction failed as a result of an invalid credit card number. Check the number or attempt with another card. 10001 Internal Error Internal Error 10001 Internal Error The transaction could not be loaded 10001 ButtonSource value truncated.
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 amount is not a valid number 10004 Transaction refused because of an invalid argument. See additional error messages for details. The amount exceeds the max limit of a single mass pay item ~1 10004 Transaction refused because of an invalid argument. See additional error messages for details.
Using the Mass Payments API MassPay Error Codes Error Code Short Message Long Message 10311 Unable to submit payment Unable to submit payments for masspay 10312 Masspay server error The masspay server has reported errors 10313 Masspay Invalid Data The masspay input file includes invalid data 10314 Masspay input parse error The input to the masspay server is incorrect. Please make sure that you are using a correctly formatted input.
3 28 Using the Mass Payments API MassPay Error Codes February 2012 Mass Payments User Guide
4 Mass Payments Reporting Read the following topics to learn how to review transaction information for Mass Payments: “About Mass Payments Reporting” on page 29 “Using the Reports Dashboard to Review Mass Payment Transactions” on page 29 “Using Account History to Review Mass Payment Transactions” on page 31 “Receiving Instant Payment Notifications for Mass Payments” on page 33 “Using the Settlement Report and the Transaction Detail Report” on page 35 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 Click Print to print a copy. Click Download to save the list to a file. 4 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. Select the file type you want to save from the dropdown list next to the Download button.
4 Mass Payments Reporting Viewing Transaction Logs 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. Enter the recipient’s email address in the Search for text box. 4.
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 36 Mass Payments Reporting Using the Settlement Report and the Transaction Detail Report February 2012 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 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. On the next page, you can download either a TXT or CSV file by clicking the links under Mass Payment Details. The file will include a summary of all payments, including the current status.
5 Best Practices and FAQs for Mass Payments Mass Payments FAQs Recipient did not receive the payment email Sometimes PayPal emails get redirected to a recipient’s spam folder. If this is the case, the recipient can simply log in to PayPal to view the payment. Also, double-check the email address in your Mass Payments file. There could be a misspelling or a formatting problem.
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 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.
