Skip to end of metadata
Go to start of metadata

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: Zend_Service_PayPal Component Proposal

Proposed Component Name Zend_Service_PayPal
Developer Notes
Proposers A.J. Brown, Zend liaison
Revision 0.1 - 27 February 2007: Started proposal process
0.2 - 23 March 2007: First proposal draft ready for review
0.3 - 9 June 2007: Added the MassPay API
0.4 - 17 June 2007: Added the GetTransactionDetails API
0.5 - 1 July 2007: Added PDT and IPN requirements
0.6 - 2 February 2008: Transfered proposal ownership from Shahar Evron (wiki revision: 29)

Table of Contents

1. Overview

Zend_Service_PayPal is a Zend Framework interface to the PayPal on-line payment service, through PayPal's exposed APIs. Initially, it is intended to support the lighter PayPal Name-Value Pairs (NVP) interface. Additionally, Zend_Service_PayPal will provide smaller "utility" classes for sending special requests to PayPal (eg. Payment Data Transfer requests) or receiving Instant Payment Notification messages from PayPal.
In the future, Zend_Service_PayPal might also implement a SOAP interface as an optional alternative to the NVP interface.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

  • Zend_Service_PayPal will implement the new PayPal NVP interface to the PayPal API servers
  • Zend_Service_PayPal will include a set of container classes for common PayPal data types: CreditCard, Address, Authentication Information, ...
  • Zend_Service_PayPal will allow API users to authenticate using both PayPal API Signatures and PayPal API Certificates
  • Zend_Service_PayPal will allow API users to perform the business functions:
    • DoDirectPayment
    • SetExpressCheckout
    • GetExpressCheckoutDetails
    • DoExpressCheckoutPayment
    • DoCapture
    • DoAuthorize
    • DoVoid
    • DoReauthorize
    • RefundTransaction
    • TransactionSearch
    • GetTransactionDetails
    • MassPay
  • Zend_Service_PayPal will expose methods in a way allowing abstraction between the NVP interface and the SOAP interface if it will be implemented
  • Zend_Service_PayPal will implement a common PayPal API response class allowing easy access to response messages
  • Zend_Service_PayPal will implement classes to send PayPal PDT (Payment Data Transfer) requests and receive PayPal IPN (Instant Payment Notification) requests. Both functions are not a part of PayPal's NVP API, and should be implemented as separate interfaces.
  • Zend_Service_PayPal will use Zend_Http_Client to preform HTTP requests, and will allow the developer to override the default Http_Client object (allowing the usage of custom Http_Client adapters, etc.)
  • Zend_Service_PayPal will not attempt to be built in a payment-service abstract fashion, due to the complexity of PayPal's service

4. Dependencies on Other Framework Components

  • Zend_Http_Client
  • Zend_Validate_Ccnum
  • Zend_Validate_Alnum
  • Zend_Validate_EmailAddress
  • Zend_Validate_StringLength
  • Zend_Service_Exception

5. Theory of Operation

The PayPal service object will be used in slightly different manners, depending on the API call that is preformed. Generally speaking, a single interface object is instantiated, and the API credentials are set (API user name, password and signature / certificate). Internally, the object also instantiates a Zend_Http_Client object and prepares it for an NVP request (set the method to POST, preset some always-required POST parameters, etc.).

Depending on the request type, the user will also need to instantiate additional container objects - for example, a DoDirectPayment request would require credit card information and billing address to be passed. These pieces of information will be represented in objects that will be passed to the interface object when calling an API method.

Once an API method is called, the interface object will set all the required POST parameters, and send the HTTP request. All API calls will return a common Response object - containing all the information in the PayPal response (status, transaction ID, failure reasons, etc.)

Note: Supporting PayPal certificate authentication might require improvements to Zend_Http_Client - namely resolving ZF-1004.

6. Milestones / Tasks

  • Milestone 1: design notes will be published here
  • Milestone 2: As part of the proposal process, integration with other Framework components will be considered (eg. Zend_Currency, Zend_Auth, Zend_Log)
  • Milestone 3: Working prototype for DoDirectPayment and ExpressCheckout calls, along with container classes for common data objects
  • Milestone 4: Unit tests exist, work, and are checked into SVN.
  • Milestone 5: Initial documentation exists.
  • Milestone 6: All API other listed API calls are working using the NVP interface, along with unit tests and documentation.
  • Milestone 7: (optional, depending on a separate proposal) Implementation of the SOAP interface
  • Milestone 8: (optional, depending on a separate proposal) Implementation of a PayPal Instant Payment Notification gateway

7. Class Index

  • General
    • Zend_Service_PayPal_Exception
  • PayPal Business API access
    • Zend_Service_PayPal_Interface
    • Zend_Service_PayPal_Nvp
    • Zend_Service_PayPal_Soap (optional, depending on a separate proposal)
    • Zend_Service_PayPal_Response
  • Data Containers
    • Zend_Service_PayPal_Data_Exception
    • Zend_Service_PayPal_Data_Address
    • Zend_Service_PayPal_Data_AuthInfo
    • Zend_Service_PayPal_Data_CreditCard
    • Zend_Service_PayPal_Data_User
    • Zend_Service_PayPal_Data_OrderItem
    • Zend_Service_PayPal_Data_MassPayReceiver
  • Payment Data Transfers
    • Zend_Service_PayPal_Pdt
    • Zend_Service_PayPal_Pdt_Response
    • Zend_Service_PayPal_Pdt_Exception

8. Use Cases

UC-1: Charging a credit card using the DirectPayment API call
UC-2: Charding a PayPal account through Express Checkout

Start the checkout process:

After the user is redirected back from PayPal after authorizing the payment:

UC-3: Preforming a Mass Payment to customers
UC-4: Getting information about a transaction using GetTransactionDetails

9. Class Skeletons



Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Mar 01, 2007

    <p>good idea, i may use this proposal in my work.</p>

  2. Mar 23, 2007

    <p>Looks great, Shahar. You may want to update your use cases to match your skeletons, though (parameter order, for example).</p>

  3. Mar 23, 2007

    <p>Rather than integrate just PayPal, why not a Services_Payment or something similar. You could use adapters for paypal,, linkpoint, etc. I know there is a pear class trying to accomplish something similar, and I would deffinitly be willing to contribute the code.</p>

    1. Mar 24, 2007

      <p>When I started looking at this there was already Gavin's proposal for <a href="">Zend_Service_Payment</a> - I am not really familiar with any other payment services so it was very hard for me to think about a generic adapter-based service. </p>

      <p>The PayPal API exposes many features which to me seemed specific and hard to generalize (eg. express checkout). </p>

      <p>Can you describe your ideas of creating such generic interface?</p>

      1. Mar 24, 2007

        <p>Sorry - it's not Gavin's <ac:emoticon ac:name="wink" /> My apologies to Richard.</p>

      2. Mar 27, 2007

        <p>I suppose it could extend a common Zend_Payment_Interface, Zend_Payment_Data_Address_Interface, etc. but I'm not sure if enough value would be added for the hassle involved. As you said, there are a lot of unique features that would be hard to abstract out, although at the core you are doing the same thing with each payment service.</p>

  4. Jun 21, 2007

    <p>Note that while the proposal has not been accepted or rejected yet, the code suggested above has been committed to the Zend Framework laboratory, available from Subversion repository at <a class="external-link" href=""></a> for all those who want to test it and propose improvements.</p>

    1. Jul 22, 2008


      <p>can you update the status of this proposal?</p>

      <p>The code "moved" here, in case people are looking for it:
      <a class="external-link" href=""></a></p>

  5. Jun 22, 2007

    <p>Does it implement subscriptions as well?</p>

  6. Jul 18, 2007

    <p>The proposal lists PDT and IPN as a requirement but only PDT is mentioned in the class list. Also later in the milestones it's stated that IPN should be a seperate proposal.</p>

    <p>When using PDT, I would imagine that like myself, other developers might either be required or prefer to use IPN for verification and other back-end operations instead of the PDT data. So in this case I think if IPN goes to a seperate proposal, then PDT should go with it since the two "methods" will commonly be used together.</p>

    <p>There will probably be scenarios with using payments pro or payflow pro whereby an order or transaction might be amended or added to, or perhaps there's just a hold on a payment that gets released. In this case IPN might be the choice of interaction. I'm not sure how common a scenario this might be, just some food for thought with regards to IPN being a seperate proposal. Perhaps it should be in the base service component?</p>

    <p>I see in the laboratory the code is renamed to Zend_Service_PayPal rather than Zend_Service_Paypal_Nvp and a quick peek at Zend_Service_PayPal code shows that it's assuming the use of the name/value API. I have no idea as to the uptake or % use on either the NVP or the SOAP API's for paypal; but if it's a strong possibility that the SOAP API gets implimented would it not be a prudent step to have a bit more absraction at this stage rather than assume the base Zend_Service_PayPal class will use NVP?</p>

    <p>Code looks good Shahar <ac:emoticon ac:name="smile" /> </p>

    <p>I think this component will ultimately prove to be very popular, i'd like to see it progress a.s.a.p. </p>

    1. Jul 18, 2007

      <p>About IPN: I was actually going to add it to <strong>this</strong> proposal. I have a working draft of an IPN handler in fact...</p>

      <p>About abstracting the NVP API: I was thinking about this initially, but since the NVP and SOAP APIs AFAIK expose the same functionality, I was wondering whether this actually worth the effort. Also, I was thinking whether using and adapter /factory patterns was smart in this case, or whether it would be simpler to just create two different classes (implementing the same interface) that are instantiated directly:</p>

      <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
      // Adapter / Factory
      $paypal = Zend_Service_PayPal::factory('NVP');
      // Replaceable by 'Zend_Service_PayPal::factory('SOAP');'

      // Direct instantiation
      $paypal = new Zend_Service_PayPal_Nvp(); // Replaceable by 'new Zend_Serive_PayPal_Soap();'

      1. Jul 19, 2007

        <p>That's a fair point about the funcionality being equivalent between the NVP and SOAP API's, probably not worth the effort.</p>

        <p>With regards to a factory Vs. direct instantiation. I'd say leave it up to the developer to create a factory if required ( since i'm really struggling to think of many scenarios where I might want to use one for this component ).</p>

  7. Oct 17, 2007


    <p><a class="external-link" href=""></a></p>

    <p>The developer APIs keys:</p>

    <p>API username<br /></p>

    <p>API password<br />

    <p>API signature<br />

    <p>The signature is 58 chars long, so errors on use</p>



    1. Oct 17, 2007

      <p>Hi Ian,</p>

      <p>Are you commenting on the proposal or reporting a bug in the laboratory code? If it's a comment, I didn't really understand it - so please try to be more descriptive. </p>

      <p>If you're reporting a bug, this is not the place. Please join and e-mail (keep in mind that the laboratory code is in no way fully tested and should not be considered stable for production use).</p>


      1. Oct 17, 2007

        <p>well two things</p>

        <p>helping people to test it with the dev keys, and also pointing out that these didnt work as something wierd was going on.</p>

        <p>I am testing your code quite thoroughly today but am new to this part of the framework so any advice is welcome.</p>

        <p>I will join this list then.</p>



  8. Aug 20, 2008

    <p>Is there any status update on this one ?</p>

  9. Aug 24, 2008


    <p>Unfortunately I have no time to work on this. If anyone wants to inherit the existing code / proposal, I'd be happy.</p>


    1. Dec 18, 2008


      <p>I would be interested in taking up leadership on this proposal if it will get it moving down the pipes. I have enough experience with PayPal to ensure a quality deliverable.</p>

      1. Dec 18, 2008

        <p>It would be very nice to have this component.</p>

    2. Feb 01, 2009

      <p>I'll be willing to help Aj Brown on this if help is needed.</p>

      <p>SpotSec<br />

  10. Feb 02, 2009

    <p>Hi Guys,</p>

    <p>Im' working on getting permissions to edit the proposal. Once that's done, we'll get this moving again.</p>

  11. Feb 11, 2009

    <p>Just an idea: wouldn't it be nice if this would become something like Zend_Payment?</p>
    <li>With adapters for use with the many different payment gateways or possibly even your own?</li>
    <li>With a way to generate a Zend_Form to initiate the payment process with gateways that require this.</li>
    <li>With a way to handle a Zend_Controller_Request as a payment confirmation/cancellation.</li>

    <p>Loosely coupled to allow stand-alone use of course.</p>

    <p>At least it sounded useful to me at the time of writing <ac:emoticon ac:name="smile" /></p>

    1. Feb 20, 2009

      <p>We already had the proposal: <a class="external-link" href=""></a></p>

      <p>But it is not developed anymore.</p>

  12. Mar 23, 2009

    <p>Until the project is rolling again, is there a download with all the files arranged easily for us to experiment with? I have been battling with the code for several days. I have found the laboratory (that took some work)... and that has been helpful, BUT, it does not have the test-a-payment code wrapped in. </p>

    <p>I love this project... anything I learn, I would quite like to contribute back.</p>


  13. Apr 21, 2009

    <p>I would love to see DoReferenceTransaction as well as ManagePendingTransactionStatus in this in addition to what it already has.</p>

    1. Apr 27, 2009


      <p>This and almost every other API Call available will exist under Zend_Payment component. That will allow a unified API to various payment providers and gateways. Will blog about the usage and examples tomorrow.</p>


  14. Aug 08, 2009

    <p>Is this still under development? i'd love to see this running. If you need some help, don't hesitate to contact me. <ac:emoticon ac:name="smile" /></p>

    1. Aug 14, 2009

      <p>I'd like to echo this. Any help required, let me know. I've got a complete IPN component if required.</p>

      <p>If this proposal is dead in the water due to resources, please pass it on to someone else.</p>

      1. Aug 14, 2009

        <p>Hey Guys, </p>

        <p>This is still under development, albeit at a much slower pace. I'm working on another project, which takes advantage of this component, so it's getting parallel development. Once I'm done with this release cycle, I update the latest code and the necessary changes to the proposal. On the brighter side, this has allowed me to restructure things in a way that works better.</p>

        1. Aug 14, 2009


          <p>I would also like to help with this if possible</p>

          <p>Im still using a modified version of Shahar did</p>

          <p> So if you need any more devs let me know</p>

          <p>Ian </p>

  15. Aug 19, 2009

    <p>I'll toss my hat into the help pool as well.</p>

  16. Sep 20, 2009

    <p>Hi All,</p>

    <p>I will be putting this up on Google Code shortly. I wil post the details here so that everyone whom would like to contribute can do so. </p>

  17. Oct 22, 2009

    <p><a class="external-link" href=""></a></p>

    <p>Please send me an invite request to aj .. AT .. ajbrown .. DOT .. org with your gmail username for commit access. Lets get this thing finished up.</p>

    <p>you'll notice that it's relatively simple right now. I have 2 projects that will be making use of the various API interfaces, so it'll start to get filled in quickly.</p>

    <p>Once in the project, please develop in your own branch.</p>

  18. Dec 20, 2009

    <p>After putting some thought into it, I've decided that we should drop support for the SOAP API. I can't seem to come up with a justifiable reason for someone using this component to want to specify the SOAP API. The only real scenario I can come up with is if the user is using a proxy to transfer between their web server and PayPal which requires SOAP. This is an edge case, however.</p>

    <p>In the mean time, the architecture will continue to use an Adapter pattern, in the case that an end user would like to create their SOAP compatible adapter.</p>

    <p>Are there any arguments against this decision?</p>

    1. Dec 21, 2009

      <p>+1, go ahead!</p>

      <p>Still about adapters. How often they change/add some stuff in this API? If this is common like once a semester/year, it could be nice if the adapters provide us a way to make request directly, like a "make-urls-by-yourself". This way the API will work even for those that don't update their zend library... i am thinking about that since some weeks ago.</p>

      <p>so, i think that's all, i'm not expert in paypal, but here is my 2 cents</p>