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.

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.

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.

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.

NVP MassPay response message

MassPay 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's credit card is not in the list of allowed countries of the gaming merchant

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

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

14764

Regulatory review - Pending

14765

Regulatory review - Blocked

14766

Compliance violation - Declined by TravelRule; provide required information to verify identity of sender or receiver. Please contact PayPal Support for more information.

14767

Receiver is unregistered

14768

Receiver is unconfirmed

14769

Youth account recipient

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.