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 `MassPayRequest` can include up to 250 `MassPayItem`s. 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 `MassPayItem`s. 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.

Mass Payments reporting