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

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 MassPayRequest can include up to 250 MassPayItems. For a list of fields that you repeat for each recipient, see the MassPayItem type.
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, or ReceiverID depending on the value passed for ReceiverType, 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 MassPay request. A single request must include items that are of the same currency.
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 MassPayRequest can include up to 250 MassPayItems. See MassPayItem type below for a list of fields that you repeat for each recipient.

MassPayItem type

Note: You must specify either L_EMAIL, L_RECIEVERPHONE, or L_RECEIVERID depending on the value passed for ReceiverType, 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 MassPay request. A single request must include items that are of the same currency.
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.

Next

Mass Payments reporting

Popular Search Queries
PayPal Help
FAQ's

FAQ's

Forum

Tech Support Community

PayPal Community