Use the Mass Payments API
Note: The MassPay API is Deprecated as of September 1, 2017. For new integrations, see the Payouts Overview.
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.
Note: For more information on using Mass Payments from your PayPal account, see Using Mass Payments in Your PayPal Account.
Read the following topics to learn how to implement Mass Payments using the API.
- Call the MassPay API
- MassPay API using SOAP
- MassPay API using NVP
- MassPay error codes
- MassPay failed transactions IPN reason codes
- MassPay API and Permissions Service
Call the MassPay API
The MassPay API lets you send payments to up to 250 recipients with a single API call. You specify the payment amount for each recipient individually, but you must use the same currency type for all payments in a MassPay API request. You can identify recipients either by email address, US mobile phone number, or their PayPal customer account number.
PayPal receives the MassPay request and returns a response indicating success or failure. If PayPal returns a successful response, then PayPal processes the payments. If you have Instant Payment Notifications (IPN) enabled, PayPal sends a notification to the Notify URL specified in your account profile. If you do not have IPN enabled, you can view the details of the MassPay transaction in your PayPal account.
The PayPal API is available in both a SOAP interface as well as a Name-Value Pair (NVP) interface.
Note: If you're not familiar with SOAP or NVP, see PayPal SOAP API basics or PayPal NVP overview.
MassPay API using SOAP
The following sections contain a list and descriptions of the MassPay fields:
SOAP MassPay request message
Field | Type | Description |
---|---|---|
EmailSubject (Opt) |
xs:string |
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 (Req) |
ebl:MassPayItemType |
Details of each payment.Note: A single |
ReceiverType (Opt) |
ebl:ReceiverInfoCodeType |
Indicates how you identify the recipients of payments in this call to MassPay . It is the same for all recipients. Must be either EmailAddress , PhoneNumber , or UserID . |
MassPayItem types
This table shows each of the MassPayItem
types.
Note: You must specify either
ReceiverEmail
,ReceiverPhone
, orReceiverID
depending on the value passed forReceiverType
, and all MassPay items in a single request must use the same field to identify recipients.
Field | Type | Description |
---|---|---|
ReceiverEmail |
ebl:EmailAddressType |
Email address of recipient.Character length and limitations: 127 single-byte characters maximum. |
ReceiverPhone |
xs:string |
Mobile phone number of recipient. |
ReceiverID |
ebl:UserIDType |
Unique PayPal customer account number. This value corresponds to the value of PayerID returned by GetTransactionDetails . Character length and limitations: 17 single-byte characters maximum. |
Amount |
cc:BasicAmountType |
Payment amount. You must set the currencyID attribute to one of the three-character currency codes for any of the supported PayPal currencies. The decimal separator must be a period.Note: You cannot mix currencies in a single |
UniqueId (Opt) |
xs:string |
Transaction-specific identification number for tracking in an accounting system. Character length and limitations: 30 single-byte characters. No whitespace allowed. |
Note (Opt) |
xs:string |
Custom note for each recipient. Character length and limitations: 4,000 single-byte alphanumeric characters |
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.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
Note: Carriage returns have been added to the code example for easier reading.
The following sections contain a list and descriptions of the MassPay fields:
NVP MassPay request message
Field | Description |
---|---|
METHOD (Req) |
Must be MassPay . |
EMAILSUBJECT (Opt) |
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 (Req) |
A three-character currency code. See Currencies and Currency Codes for specifying currencies in fields and variables. |
RECEIVERTYPE (Opt) |
Indicates how you identify the recipients of payments in this call to MassPay . Must be EmailAddress , PhoneNumber , or UserID . It is the same for all recipients.Note: A single |
MassPayItem type
Note: You must specify either
L_EMAIL
,L_RECIEVERPHONE
, orL_RECEIVERID
depending on the value passed forReceiverType
, and all MassPay items in a single request must use the same field to identify recipients.
Field | Description |
---|---|
L_EMAIL |
Email address of recipient.Character length and limitations: 127 single-byte characters maximum. |
L_RECEIVERPHONE |
Mobile phone number of recipient. |
L_RECEIVERID |
Unique PayPal customer account number. This value corresponds to the value of PayerID returned by GetTransactionDetails . Character length and limitations: 17 single-byte characters maximum. |
L_AMT |
Payment amount. You must set the currencyID attribute to one of the three-character currency codes for any of the supported PayPal currencies. The decimal separator must be a period.Note: You cannot mix currencies in a single |
L_UNIQUEID (Opt) |
Transaction-specific identification number for tracking in an accounting system. Character length and limitations: 30 single-byte characters. No whitespace allowed. |
L_NOTE (Opt) |
Custom note for each recipient. Character length and limitations: 4,000 single-byte alphanumeric characters |
NVP MassPay response message
The fields in the response are the NVP common response fields.
MassPay error codes
See API error codes.
MassPay failed transactions IPN reason codes
These codes are returned to the Instant Payment Notification (IPN) listener you set up for your MassPay requests. For more information on MassPay IPN variables see the MassPay IPN variables table in the IPN guide.
The IPN MassPay reason_code
variable is set only if status
= Failed
.
Reason code | Description |
---|---|
1001 |
Receiver's account is invalid |
1002 |
Sender has insufficient funds |
1003 |
User's country is not allowed |
1004 |
User funding source is ineligible |
3004 |
Cannot pay self |
3014 |
Sender's account is locked or inactive |
3015 |
Receiver's account is locked or inactive |
3016 |
Either the sender or receiver exceeded the transaction limit |
3017 |
Spending limit exceeded |
3047 |
User is restricted |
3078 |
Negative balance |
3148 |
Receiver's address is in a non-receivable country or a PayPal zero country |
3501 |
Email address invalid; try again with a valid email ID |
3535 |
Invalid currency |
3547 |
Sender's address is located in a restricted State (e.g., California) |
3558 |
Receiver's address is located in a restricted State (e.g., California) |
3769 |
Market closed and transaction is between 2 different countries |
4001 |
Internal error |
4002 |
Internal error |
8319 |
Zero amount |
8330 |
Receiving limit exceeded |
8331 |
Duplicate mass payment |
9302 |
Transaction was declined |
11711 |
Per-transaction sending limit exceeded |
14159 |
Transaction currency cannot be received by the recipient |
14550 |
Currency compliance |
14761 |
The mass payment was declined because the secondary user sending the mass payment has not been verified |
14763 |
Regulatory review - Pending |
14764 |
Regulatory review - Blocked |
14765 |
Receiver is unregistered |
14766 |
Receiver is unconfirmed |
14767 |
Receiver is a youth account |
14800 |
POS cumulative sending limit exceeded |
MassPay API and the Permissions Service
Similar to other PayPal NVP/SOAP APIs, you can call the MassPay API on behalf of another PayPal account holder after this third party grants permission by using the Permissions Service. To learn more about the Permissions Service, see the Permissions Service Get Started.