Hack 96 Issue Payments en Masse with the Mass Pay API

Send out a large number of payments all at once with the Mass Pay feature through the API .

As described in [Hack #77] , PayPal allows you to send many payments at once through the PayPal web site. Using the Mass Pay API and some slight modifications to the code in [Hack #88] , you can also do this from your own applications.

You can pay up to 250 payees at once using Mass Pay. To make more than 250 payments, you'll need to call Mass Pay repeatedly.

8.12.1 Setting up the Request

The first thing to do is set up a simple tab-delimited text file that contains all the information about your payees, as shown in Figure 8-13.

Figure 8-13. Using a simple tab-delimited text file to store the information about the recipients of your payments

List the recipients' email addresses in the first column and the corresponding payment amounts in the second column. Include an optional third column to list a unique identifier for each recipient for tracking and reconciliation purposes. The optional fourth column lets you include a customized note to be sent to each of your recipients.

8.12.2 The Code

This code uses the MassPayReq , MassPayRequestType , MassPayRequestItemType , and MassPayResponseType objects generated by the web reference in order to process the Mass Pay request.

This code requires the SSL certificate generated in [Hack #88] .

 // Load the Certificate X509Certificate certificate = X509Certificate.CreateFromCertFile(certPath); // Create the API Service PayPalAPIInterfaceService service = new PayPalAPIInterfaceService( ); service.Url = url;                          // Add the X509 Cert to the service for authentication service.ClientCertificates.Add(certificate); // Create the MassPay Request Item 1.  MassPayRequestItemType masspayRequestItem = new MassPayRequestItemType( ); // create the Amount BasicAmountType amount = new BasicAmountType( ); amount.currencyID = CurrencyCodeType.USD; amount.Value = "0.67"; masspayRequestItem.Amount = amount; // create the recipient email masspayRequestItem.ReceiverEmail = "[e-mail]"; // create the optional unique id (for your own benefit) masspayRequestItem.UniqueID = "some unique id"; // create the optional Note masspayRequestItem.Note = "some note"; // Create the MassPay Request  2.  MassPayRequestType masspayRequest = new MassPayRequestType( ); // you can set an email subject if you want to.  // This will be the subject of the email that your payees are going                  to receive masspayRequest.EmailSubject = "some email subject"; masspayRequest.MassPayRequestItemDetails = new MassPayRequestItemType[ 1 ]; // add the previously created MassPayRequestItemType object to this array masspayRequest.MassPayRequestItemDetails[0] = masspayRequestItem; MassPayReq request = new MassPayReq( ); request.MassPayRequest = masspayRequest; // Build the Security Header CustomSecurityHeaderType securityHeader = new CustomSecurityHeaderType( ); UserIdPasswordType userIdPassword = new UserIdPasswordType( ); userIdPassword.Username = ""; // Insert your API username here userIdPassword.Password = ""; // Insert your API password here userIdPassword.Subject = ""; securityHeader.Credentials = userIdPassword; securityHeader.MustUnderstand = true; service.RequesterCredentials = securityHeader; MassPayResponseType response = service.MassPay(request); Console.WriteLine("Ack: " + response.Ack.ToString( )); Console.WriteLine("Correlation ID: " + response.CorrelationID); Console.WriteLine("Timestamp: " + response.Timestamp.ToString( )); 

8.12.3 Running the Hack

When you successfully execute the code [Hack #90] , the Ack code returned will be Success :

 Ack: Success CorrelationID:  Timestamp: 4/27/2004 10:25:30 AM 

Each payee is represented in the code as a MassPayRequestItemType object. Create the initial MassPayRequestItemType instance (line 1) and a BasicAmountType instance that contains the amount, and add it to the item request. Also create the recipient's email, unique ID, and note, and add them to the item request.

Note that this code creates only one MassPayRequestItemType object (line 2). You can repeat the steps to fill in as many objects as you want and thus overcome the limit of 250 payees. Typically, the way to do this is to read the individual item details from the tab-delimited file and create the objects on the fly. That way, you should be able to create a list of MassPayRequestItemType objects.

When you send a payment with Mass Pay, you pay the seller fees [Hack #14] that would otherwise be assessed to your recipients.

Souvik Das, Rob Conery, and Dave Nielsen