MassPay API

 

The MassPay API is the programmatic counterpart to the Mass Payment feature available through the PayPal website. You can include up to 250 payments per MassPayRequest. You must have a PayPal balance in each currency in which you want to make a payment and have sufficient funds to cover the entire Mass Payment amount and fee. You cannot mix currencies in the same MassPayRequest; a separate request is required for each currency.

The posting of payment transactions to individual recipient accounts is not handled by the MassPay API but by a separate PayPal process.

Instant Payment Notification

The MassPay API triggers the sending of an Instant Payment Notification to the recipient of the funds. You must check the IPN to get the necessary information you need about the transaction.

Diagram of MassPay Types

The following diagram represents the composition of the MassPayRequestType, MassPayRequestItemType, and MassPayResponseType elements.

Figure 7.1

MassPay Types

MassPayRequest

Process payments en masse to up to 250 different recipients.

Table 7.1

MassPayRequestType Fields

Field	Description	Required?
EmailSubject	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	No
ReceiverType	ebl:ReceiverInfoCodeType Indicates how you identify the recipients of payments in all MassPayItems: either by EmailAddress (ReceiverEmail in MassPayItem) or by UserID (ReceiverID in MassPayItem). See Table 7.2, “ReceiverInfoCodeType Enumeration.”	No
MassPayItem	ebl:MassPayItemType Details of each payment. Note: A single MassPayRequest can include up to 250 MassPayItems See Table 7.3, “MassPayItemType Fields.”	Yes

Table 7.2

ReceiverInfoCodeType Enumeration

Field	Description	Required?
EmailAddress	Email address of recipient on file with PayPal. Character length and limitations: 12 single-byte alphanumeric characters.	No
UserID	Unique PayPal customer account number. Character length and limitations: 6 single-byte characters maximum.	No

Table 7.3

MassPayItemType Fields

Field	Description	Required?
ReceiverEmail	ebl:EmailAddressType Email address of recipient. Important: You must specify either ReceiverEmail or ReceiverID, but you must not mix ReceiverEmail and ReceiverID in the group of MassPayItems. Use only one or the other, but not both, in a single request. Character length and limitations: 127 single-byte characters maximum.	No
ReceiverID	xs:string Unique PayPal customer account number. This value corresponds to the value of PayerID returned by GetTransactionDetails. Important: You must specify either ReceiverEmail or ReceiverID, but you must not mix ReceiverEmail and ReceiverID in the group of MassPayItems. Use only one or the other, but not both, in a single request. Character length and limitations: 17 single-byte characters maximum.	No
Amount	ebl:BasicAmountType Payment amount. Note: You must set the currencyID attribute to one of the three-character currency codes for any of the supported PayPal currencies. See “PayPal-Supported Transactional Currencies”. Important: You cannot mix currencies in a single MassPayRequest. A single request must include items that are of the same currency.	Yes
UniqueId	xs:string Transaction-specific identification number for tracking in an accounting system. Character length and limitations: 30 single-byte characters. No whitespace allowed.	No
Note	xs:string Custom note for each recipient. Character length and limitations: 4,000 single-byte alphanumeric characters	No

MassPayResponse

Response to MassPayRequest.

The elements returned are the same as for AbstractResponseType. See “AbstractResponseType”.

For error codes and messages and their meanings, see Appendix A, “Error Codes and Messages for All PayPal APIs.”