MassPay


The MassPay API can greatly facilitate using PayPal to send automated payments to large numbers of individuals, providing you have a U.S.-based business account. This type of process could be used if employees are paid via PayPal, or you have a regular relationship with a supplier that requires regular payments. Unlike the majority of PayPal payments, the sender (you), not the receiver, is responsible for transaction fees. This means that more money will be deducted from your account than the mass payment totals. The processing fee is currently 2% of the payment, with a cap of USD $1.00 per item. You can send up to 250 payments in the same currency at a time with the MassPay API. More items than that, or different currencies, must be split into multiple transactions.

Using the MassPay API is a little more complex than previous examples, because there is an additional layer of nesting involved to allow for multiple payments, each with their own variables. A request looks something like this (continuing to trim the namespace declarations to save space):

 <SOAP-ENV:Envelope  SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">  <SOAP-ENV:Header>   <RequesterCredentials xmlns="urn:ebay:api:PayPalAPI"    SOAP-ENV:mustUnderstand="1">    <Credentials xmlns="urn:ebay:apis:eBLBaseComponents">     <Username>stb_api1.preinheimer.com</Username>     <Password>ZJXaRwTBoL8m</Password>     <Subject/>    </Credentials>   </RequesterCredentials>  </SOAP-ENV:Header>  <SOAP-ENV:Body>   <MassPayReq xmlns="urn:ebay:api:PayPalAPI">    <MassPayRequest xsi:type="ns:MassPayRequestType">     <Version xmlns="urn:ebay:apis:eBLBaseComponents"      xsi:type="xsd:string">1.0</Version>     <EmailSubject xsi:type="ebl:string">Work</EmailSubject>     <MassPayItem xsi:type="ebl:MassPayItemType">      <ReceiverEmail xsi:type="ebl:string">bigbird@example.com</ReceiverEmail>      <Amount currency xsi:type="ebl:string">100.00</Amount>      <Note xsi:type="ebl:string">Thanks</Note>     </MassPayItem>     <MassPayItem xsi:type="ebl:MassPayItemType">      <ReceiverEmail xsi:type="ebl:string">oscar@example.com</ReceiverEmail>      <Amount currency xsi:type="ebl:string">100.00</Amount>      <Note xsi:type="ebl:string">Thanks</Note>     </MassPayItem>    </MassPayRequest>   </MassPayReq>  </SOAP-ENV:Body> </SOAP-ENV:Envelope> 

This additional depth of elements leaves three options: either the MakeAPICall() function presented earlier can be adapted to allow for this additional depth, the additional depth can be handled when making the call, or an entire new function can be written to handle just this type of call. I would rather leave the makeAPICall() function in its current state. It's pretty easy to read and relatively easy to debug if it comes to that. I would also rather not make an entire new function. If cURL changes need to be made down the line, or changes to the SOAP header, for example, it would increase upkeep, which leaves me with handling the depth when the call is made. Fortunately, the resulting code still looks pretty good:

 function massPay($emails, $subject, $amount) {   $parameters = array();   $parameters[] = array("EmailSubject", "ebl:string", "$subject");   foreach($emails as $email)   {     $parameterList = "\t<ReceiverEmail xsi:type=\"ebl:string\">$email       </ReceiverEmail>\n";     $parameterList .= "\t<Amount currencyID=\"USD\" xsi:type=\"ebl:string\">$amount       </Amount>\n";     $parameterList .= "\t<Note xsi:type=\"ebl:string\">Thanks</Note>\n";     $parameters[] = array("MassPayItem", "ebl:MassPayItemType", "$parameterList");   }   $xml = makeAPICall("MassPay", $parameters);   return $xml; } 

Here a similar format is used as in earlier examples — the parameters array is populated with the optional and required elements for the call. In this case you "hide" the additional layer (or depth) of elements within the one MassPayItem element, allowing the makeAPICall() function to be used without any changes.

Note 

I debated how to handle this for quite a while. A more elegant solution might have been to introduce recursion within the makeAPICall() function to allow it to handle any required depth of parameters (and in fact this is the method that was used for the more complex eBay calls discussed in another chapter). In this case I sided with simplicity.

PayPal doesn't return much when it comes to making a mass payment — merely success or failure of the payment. To get more details, you will need to perform a search (use the TransactionSearch call with the TransactionClass element set to MassPay).

 <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"   xmlns:ebl="urn:ebay:apis:eBLBaseComponents" xmlns:ns="urn:ebay:api:PayPalAPI">   <SOAP-ENV:Header>     <Security xmlns="http://schemas.xmlsoap.org/ws/2002/12/secext"       xsi:type="wsse:SecurityType">     </Security>     <RequesterCredentials xmlns="urn:ebay:api:PayPalAPI"       xsi:type="ebl:CustomSecurityHeaderType">     <Credentials xmlns="urn:ebay:apis:eBLBaseComponents"       xsi:type="ebl:UserIdPasswordType">       <Username xsi:type="xs:string"></Username>       <Password xsi:type="xs:string"></Password>       <Subject xsi:type="xs:string"></Subject>     </Credentials>     </RequesterCredentials>   </SOAP-ENV:Header>   <SOAP-ENV:Body >     <MassPayResponse xmlns="urn:ebay:api:PayPalAPI">       <Timestamp xmlns="urn:ebay:apis:eBLBaseComponents">2005-04-19T03:48:25Z         </Timestamp>       <Ack xmlns="urn:ebay:apis:eBLBaseComponents">Success</Ack>       <Version xmlns="urn:ebay:apis:eBLBaseComponents">1.000000</Version>       <Build xmlns="urn:ebay:apis:eBLBaseComponents">1.0006</Build>     </MassPayResponse>   </SOAP-ENV:Body> </SOAP-ENV:Envelope> 

For this example, several of the values (the amount, for example) were restricted in a manner that the API does not require or enforce. If you want to send different amounts, or different notes to different recipients, the changes required should be quick.




Professional Web APIs with PHP. eBay, Google, PayPal, Amazon, FedEx, Plus Web Feeds
Professional Web APIs with PHP. eBay, Google, PayPal, Amazon, FedEx, Plus Web Feeds
ISBN: 764589547
EAN: N/A
Year: 2006
Pages: 130

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net