|o||LWP - to make HTTP requests|
|o||Crypt::SSLeay - to enable LWP perform https (SSL) requests. If for any reason you are not able to install Crypt::SSLeay, you will need to update $Business::PayPal::IPN::GTW to proper, non-ssl URL.|
Business::PayPal::IPN supports all the variables supported by PayPal IPN independent of its version. To access the value of any variable, use the corresponding method name. For example, if you want to get the first name of the user who made the payment (first_name variable):
o new() - constructor. Validates the transaction and returns IPN object. Optionally you may pass it <B>queryB> and <B>uaB> options. <B>queryB> denotes the CGI object to be used. <B>uaB> denotes the user agent object. If <B>uaB> is missing, it will use LWP::UserAgent by default. If the transaction could not be validated, it will return undef and you should check the error() method for a more detailed error string: o vars() - returns all the returned PayPal variables and their respective values in the form of a hash. o query() - can also be accessed via cgi() alias, returns respective query object o response() - returns HTTP::Response object, which is the response returned while verifying transaction through PayPal. You normally never need this method. In case you do for any reason, here it is. o user_agent() - returns user agent object used by the library to verify the transaction. Name of the agent is Business::PayPal::IPN/#.# (libwww-perl/#.##).
my $fname = $ipn->first_name()
To get the transaction id (txn_id variable)
my $txn = $ipn->txn_id()
To get payment type (payment_type variable)
$type = $ipn->payment_type()
and so on. For the list of all the available variables, consult IPN Manual provided by PayPal Developer Network. You can find the link at the bottom of http://www.paypal.com.
In addition to the above scheme, the library also provides convenience methods such as:
o status() - which is a shortcut to payment_status() o completed() - returns true if payment_status is Completed. o failed() - returns true if payment_status is Failed. o pending() - returns true if payment_status is Pending. Return value is also the string that explains why the payment is pending. o denied() - returns true if payment_status is Denied.
Methods can return 1, 0 or undefined as well as any other true value. The distinction between 0 (which is false) and undefined (which is also false) is important:
$ipn->completed eq undef and print "Not relevant for this transaction type"; $ipn->completed == 1 and print "Transaction was completed"; $ipn->completed == 0 and print "Transaction was NOT completed";
In other words, methods return undef indicating this variable is not relevant for this transaction type (txn_type). A good example for such transactions is subscr_signup transaction, that do not return any payment_status nor txn_id variables. Methods return 0 (zero) indicating failure. They return 1 (one) or any other true value indicating success.
If for any reason your PayPal IPN solutions dont work as expected, you have no other choice but debugging the process. Although it sounds complex, it really is not.All you need to do is get your IPN script to dump Business::PayPal::IPN object into a file and investigate to see what exactly is happening. For this reason, we provide dump() method which does just that:
o dump([$filename] [,$indent]) - for dumping Business::PayPal::IPN object. If used without any arguments, simply returns the object as Perl data structure. If filename is passed as the first argument, object is dumped into the file. The second argument, if present, should be a value between 1 and 3 to indicate how well indented the dump file should be. For debugging purposes, I believe 2 is enough, but go ahead and try out for yourself to compare differences.Note that the object is dumped only once to the same file. So after investigating the dump, you may need to remove the file or dump to another file instead.
Interpreting the dump file may seem tricky, since it is relatively big file. But you dont need to understand everything in it. Simply look for the attribute called _PAYPAL_VARS. It is a hashref that keeps all the variables returned from PayPal server. These are also the methods that are available through Business::PayPal::IPN object.
You can also investigate the content of response attribute. It holds the HTTP::Response object. Look for the _content attribute of this object. This is what was returned from PayPal.com in response to your request. Ideally, this should hold VERIFIED. INVALID is also explainable though :-).
Before you do any dumping around, include the following lines on top of your IPN script if you havent done so already. This will ensure that when PayPal.com calls your IPN script, all the warnings and error messages, if any, will be saved in this file.
Following global variables are available:
o $Business::PayPal::IPN::GTW - gateway url to PayPals Web Script. Default is https://www.paypal.com/cgi-bin/webscr, which you may not want to change. But it comes handy while testing your application through a PayPal simulator. o $Business::PayPal::IPN::SUPPORTEDV - supported version of PayPals IPN API. Default value is 1.5. You can modify it before creating ipn object (as long as you know what you are doing. If not dont touch it!) o $Business::PayPal::IPN::VERSION - version of the library
Sherzod B. Ruzmetov <firstname.lastname@example.org>
Following people contributed to this library with their patches and suggestions. Its very possible that list is not complete. Help me with it.
<B>Brian GrossmanB> Fixes in the source code. pathces/brian-grososman. <B>Thomas J MatherB> Documentation fixes. patches/thomas-mather.patch
Copyright 2003 by Sherzod B. Ruzmetov.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
THIS LIBRARY IS PROVIDED WITH THE USEFULNESS IN MIND, BUT WITHOUT EVEN IMPLIED GUARANTEE OF MERCHANTABILITY NOR FITNESS FOR A PARTICULAR PURPOSE. USE IT AT YOUR OWN RISK.
$Revision: 1.18 $
|perl v5.20.3||IPN (3)||2003-08-19|