MassPay Getting Started Guide

Note: The MassPay API is Deprecated as of September 1, 2017. For new integrations, see the Payouts Overview.

Get up and running with this service:

MassPay overview

The MassPay API operation lets you send multiple payouts with a single call. With MassPay, you can easily take care of commissions, rebates, and rewards and even make all the general payouts that come with running a business.

MassPay lets you use a single call to initiate up to 250 payouts. Creating a set of payouts with MassPay is straightforward: you identify each individual recipient and the amount of each payout.

Key MassPay concepts

To make a set of payouts with MassPay, supply the e-mail addresses of your payees, the amount of each payout, and the currency of the transactions. PayPal processes your MassPay call by taking the amount of each payout from your PayPal account and placing the funds into the PayPal account of each respective recipient. PayPal then sends an e-mail to each recipient, notifying them that they've received a payment.

When setting up a MassPay call, you can specify a customized subject line for the e-mail that PayPal distributes. You can also add a note for PayPal to include in the body of e-mail. Included in the e-mail is a link that provides an easy way for payees to log into their PayPal accounts. Once logged in, payees can manage the payments they've received.

If a payee does not have an existing PayPal account, the PayPal e-mail describes how they can create a PayPal account so they can claim their payment. PayPal holds MassPay transactions for 30 days. If a payment remains unclaimed after 30 days, the amount is returned to the payer's PayPal account.

The response from a MassPay call signals only success or failure for the call, it does not indicate the status of each individual transaction. To help account for your payouts, sign up for the daily Transaction Details report, which collects the status of your individual transactions. You can also manually track your transactions by logging into your PayPal account to view the details and status of each of your MassPay payouts.

Note: Your Premier or Business PayPal account must be whitelisted for the MassPay API before you can make MassPay calls in the live environment. However, you can test Mass Pay in the Sandbox without prior authorization. After testing your application, contact your Account Manager or contact PayPal to enable MassPay for your application in the live environment.

Make a MassPay call

To make a MassPay call:

  1. Specify the endpoint for the environment you're addressing, the operation you're calling, and the version of the API you want to use. The version number should reflect the latest version number unless you have reason to use an earlier version.

    The following endpoint uses the Sandbox NVP environment for testing purposes:

    https://api-3t.sandbox.paypal.com/nvp
    METHOD=MassPay
    VERSION=90
    
  2. Supply the API credentials for the account that is making the call:

    USER=AccountUsername
    PWD=AccountPassword
    SIGNATURE=AccountSignature
    
  3. Specify how payees are identified with the RECEIVERTYPE field.

    RECEIVERTYPE=EmailAddress
    

    Set RECEIVETYPE to EmailAddress, PhoneNumber, or the payee's PayPal UserID.

    Note: The Sandbox environment does not support PhoneNumber.

  4. Specify a three-character currency code to identify the currency in which to make the payouts:

    CURRENCYCODE=USD
    

    Note: You must use the same currency for all payouts being made in a single MassPay call. Make separate MassPay calls if you must make payouts by using different currencies.

  5. Specify the details for each payout being made by the call. Payout details include a parameter that identifies to whom the payout is being made and the payout amount.

    L_EMAIL0=payee0@example.com
    L_AMT0=15.95
    L_EMAIL1=payee1@example.com
    L_AMT1=21.50
    

    The above snippet shows the parameters for two different payouts, Note that you specify payouts using a zero-based set of parameter names.

Try it

The following example uses a cURL command to run a MassPay call. The first payout starts with 0. For example, L_EMAIL0 and L_AMT0. To see this call in action, substitute your own Sandbox API credentials in the command.

curl https://api-3t.sandbox.paypal.com/nvp \
  -s \
  --insecure \
  -d USER=AccountUsername         # Caller UserName \
  -d PWD=AccountPassword          # Caller Pswd \
  -d SIGNATURE=AccountSignature   # Caller Sig \
  -d METHOD=MassPay \
  -d VERSION=90 \
  -d RECEIVERTYPE=EmailAddress \
  -d CURRENCYCODE=USD \
  -d L_EMAIL0=payee1@example.com  # The first payout starts with "0" \
  -d L_AMT0=35.95 \
  -d L_EMAIL1=payee2@example.com \
  -d L_AMT1=21.00 \
  -d L_EMAIL2=payee3@example.com \
  -d L_AMT2=45.50

Next steps

Learn more about MassPay from the following resources: