Zend Framework: Zend_Service_PayPal Component Proposal
| Proposed Component Name | Zend_Service_PayPal |
|---|---|
| Developer Notes | http://framework.zend.com/wiki/display/ZFDEV/Zend_Service_PayPal |
| 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: 28) |
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
- PayPal API refenrece
- PayPal NVP API reference (PDF)
- PayPal NVP API PHP examples
- PayPal developer testing guide
- Zend_Service_Payment proposal
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 |
|---|
35 Comments
comments.show.hideMar 01, 2007
Louis PERRIER
good idea, i may use this proposal in my work.
Mar 23, 2007
Matthew Ratzloff
Looks great, Shahar. You may want to update your use cases to match your skeletons, though (parameter order, for example).
Mar 23, 2007
Eric Coleman
Rather than integrate just PayPal, why not a Services_Payment or something similar. You could use adapters for paypal, authorize.net, linkpoint, etc. I know there is a pear class trying to accomplish something similar, and I would deffinitly be willing to contribute the authorize.net code.
Mar 24, 2007
Shahar Evron
When I started looking at this there was already Gavin's proposal for Zend_Service_Payment - 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.
The PayPal API exposes many features which to me seemed specific and hard to generalize (eg. express checkout).
Can you describe your ideas of creating such generic interface?
Mar 24, 2007
Shahar Evron
Sorry - it's not Gavin's
My apologies to Richard.
Mar 27, 2007
Matthew Ratzloff
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.
Jun 21, 2007
Shahar Evron
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 http://framework.zend.com/svn/laboratory for all those who want to test it and propose improvements.
Jul 22, 2008
Till Klampaeckel
Shahar,
can you update the status of this proposal?
The code "moved" here, in case people are looking for it: http://framework.zend.com/svn/framework/laboratory/library/Zend/Service/
Jun 22, 2007
Till Klampaeckel
Does it implement subscriptions as well?
Jul 18, 2007
Graham Anderson
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.
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.
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?
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?
Code looks good Shahar
I think this component will ultimately prove to be very popular, i'd like to see it progress a.s.a.p.
Jul 18, 2007
Shahar Evron
About IPN: I was actually going to add it to this proposal. I have a working draft of an IPN handler in fact...
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:
Jul 19, 2007
Graham Anderson
That's a fair point about the funcionality being equivalent between the NVP and SOAP API's, probably not worth the effort.
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 ).
Oct 17, 2007
Ian Warner
Shahar,
https://www.paypal.com/en_US/ebook/PP_NVPAPI_DeveloperGuide/overview.html#2076088
The developer APIs keys:
API username
sdk-three_api1.sdk.com
API password
QFZCWN5HZM8VBG7Q
API signature
Aâ€'IzJhZZjhg29XQ2qnhapuwxIDzyAZQ92FRP5dqBzVesOkzbdUONzmOU
The signature is 58 chars long, so errors on use
Cheers
Ian
Oct 17, 2007
Shahar Evron
Hi Ian,
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.
If you're reporting a bug, this is not the place. Please join and e-mail fw-webservices@lists.zend.com (keep in mind that the laboratory code is in no way fully tested and should not be considered stable for production use).
Shahar.
Oct 17, 2007
Ian Warner
well two things
helping people to test it with the dev keys, and also pointing out that these didnt work as something wierd was going on.
I am testing your code quite thoroughly today but am new to this part of the framework so any advice is welcome.
I will join this list then.
Cheers
Ian
Aug 20, 2008
Olivier Bregeras
Is there any status update on this one ?
Aug 24, 2008
Shahar Evron
Hi,
Unfortunately I have no time to work on this. If anyone wants to inherit the existing code / proposal, I'd be happy.
Shahar.
Dec 18, 2008
A.J. Brown
Hi,
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.
Dec 18, 2008
Laurent Melmoux
It would be very nice to have this component.
Feb 01, 2009
Geoffrey Tran
I'll be willing to help Aj Brown on this if help is needed.
SpotSec
Zym-project
Feb 02, 2009
A.J. Brown
Hi Guys,
Im' working on getting permissions to edit the proposal. Once that's done, we'll get this moving again.
Feb 11, 2009
Sam Hauglustaine
Just an idea: wouldn't it be nice if this would become something like Zend_Payment?
Loosely coupled to allow stand-alone use of course.
At least it sounded useful to me at the time of writing
Feb 20, 2009
Martin Hujer
We already had the proposal: http://framework.zend.com/wiki/display/ZFPROP/Zend_Service_Payment
But it is not developed anymore.
Mar 23, 2009
Vern Baker
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.
I love this project... anything I learn, I would quite like to contribute back.
...Vern
Apr 21, 2009
J Cobb
I would love to see DoReferenceTransaction as well as ManagePendingTransactionStatus in this in addition to what it already has.
Apr 27, 2009
Vadim Vincent Gabriel
Hey,
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.
Vince.
Aug 08, 2009
Daniel Hartmann
Is this still under development? i'd love to see this running. If you need some help, don't hesitate to contact me.
Aug 14, 2009
Luke Barton
I'd like to echo this. Any help required, let me know. I've got a complete IPN component if required.
If this proposal is dead in the water due to resources, please pass it on to someone else.
Aug 14, 2009
A.J. Brown
Hey Guys,
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.
Aug 14, 2009
Ian Warner
AJ
I would also like to help with this if possible
Im still using a modified version of Shahar did
So if you need any more devs let me know
Ian
Aug 19, 2009
Sean Silvius
I'll toss my hat into the help pool as well.
Sep 20, 2009
A.J. Brown
Hi All,
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.
Oct 22, 2009
A.J. Brown
http://code.google.com/p/zendservicepaypal/
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.
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.
Once in the project, please develop in your own branch.
Dec 20, 2009
A.J. Brown
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.
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.
Are there any arguments against this decision?
Dec 21, 2009
Renan de Lima
+1, go ahead!
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.
so, i think that's all, i'm not expert in paypal, but here is my 2 cents