Resource Center : Tech Speak : <Paypal and NuSOAP>

Paypal and NuSOAP

A 'send money / mass payment' sample:

The most common paypal integration that everybody does is for accepting payments, or 'receiving money' as per paypal terms.

On the paypal website, you can send money to somebody too.. to do this with code or with integration services, there is only one way... make a 'MassPay' request with Paypal API services.

MassPay, as it says, is for sending money to multiple people at once, up to 250 recipients, and nothing stops you from sending money to just one person which is as good as the 'send money' thing on the website. But yes, when you do this, it is shown as a 'Mass Payment' transaction with a separate details link on the website, rather than like a 'send money' transcation.

Everything about the previous sample(in the previous page) and this sample, is same, except the method name and the SOAP request body. We will study these portions alone.

The MassPay request body:

$bodyReq2 = "
<MassPayReq xmlns="urn:ebay:api:PayPalAPI">
  <MassPayRequest>
    <Version xmlns="urn:ebay:apis:eBLBaseComponents">$s_Ver</Version>
    <EmailSubject xsi:type="xsd:string">my email subj</EmailSubject>

  
    <ReceiverType xmlns="urn:ebay:apis:eBLReceiverInfo">EmailAddress</ReceiverType>

 
    <MassPayItem xmlns="urn.ebay:apis:eBLMassPayItemType">
      <ReceiverEmail xmlns="urn.ebay:apis:eBLEmailAddressType">somebody@pookmail.com</ReceiverEmail>
      <ReceiverID xsi:type="xsd:string"></ReceiverID>
      <Amount xmlns="urn.ebay:apis:eBLBasicAmountType" currencyID="USD">1.50</Amount>
      <UniqueId xsi:type="xsd:string">Invoice_134213</UniqueId>
      <Note xsi:type="xsd:string">payment body message</Note>
    </MassPayItem>
  </MassPayRequest>
</MassPayReq>
";

Just like in previous example, the structure of the request is 'MassPay' appended to a 'Req', and then a child element with 'MassPay' appended to a 'Request'.. and then goes the mandatory version element, and then the inputs for the call.

MassPay requests need to have three items.

1. Email subject - subject of the mail that paypal sends to the receipients saying they have received money from you. If you have more recipients, this is the same message subject sent to everyone, so don't put usernames or user related information in the subject.

2. ReceiverType - There are two types in which you can mention receipients for the payment, either by their email IDs of their paypal account, or their paypal id. Using email is preferred more though since you can ask that information from your users easily.

The ReceiverType is a setting for the rest of the inputs. If you say EmailAddress, paypal service will read all your recipient information as emails. You cannot use emails for some recipients and IDs for some.

3. MassPayItem - This is one block of information saying who is the recipient, and what is the amount of money to send.. apart from other information like currency, unique reference number, etc.,

For sending money to more than one recipient, just add more MassPayItem elements one after the other in the request.

A MassPayItem shall have the following:

Both 'ReceiverEmail' and 'ReceiverID' elements:
If the ReceiverType = "EmailAddress", then we fill 'ReceiverEmail' element with the recipient's paypal email... else, you fill the 'ReceiverID' element with the person's paypal ID (not email ID).

'Amount' element:
This element's value says the amount that shoudl be sent to the recipient. Having this inside the MassPayItem element allows us to specify different amounts for each recipient.

You might think, you can send one SOAP request for each user rather than put them all together. But, you will save a lot of money doing it this way, and that is what MassPayment is all about. Refer to the fee section to verify this, you only spend a maximum of 2USD, how much ever money you send with a Mass Payment request. And though you can have upto 250 recipients, its all together considered as one request by Paypal services doing this way.

Notice the 'currencyID' attribute in the element. This is a mandatory attribute, and the allowed values are given in Page 21 of the API ref document.

'UniqueId' element:
This element is only for you... meaning Paypal does nothing with it but just record it as an identifier string with your transaction. The maximum number of characters this element's value can have is given in the API ref document. If the document says this is an optional element, you can leave this element if you don't want it.

I use this element for putting an invoice or payment ref id that I have in my application's database.. which provides for a way to later link each database transaction in my application to a paypal transaction.

'Note' element:
This is just the same note you would type in a texbox on paypal website, when you are sending money manually to somebody. The message in this element goes with the body of the email paypal sends to the recipient.

Again, if the document says this is an optional element, you can leave this.

Advertisement