NAME
Business::PayPal::NVP - PayPal NVP API
SYNOPSIS
use Business::PayPal::NVP;
my $nvp = new Business::PayPal::NVP( test => { user => 'foo.domain.tld',
pwd => '123412345',
sig => 'A4fksj34.KKkkdjwi.w993sfjwiejfoi-2kj3' },
live => { user => 'foo.domain.tld',
pwd => '55553333234',
sig => 'Afk4js43K.kKdkwj.i9w39fswjeifji-2oj3k' },
branch => 'test' );
##
## direct payment
##
%resp = $nvp->DoDirectPayment( PAYMENTACTION => 'Sale',
CREDITCARDTYPE => 'VISA',
ACCT => '4321123412341234',
AMT => '30.00',
EXPDATE => '022018', ## mmyyyy
CVV2 => '100',
IPADDRESS => '12.34.56.78',
FIRSTNAME => 'Buyer',
LASTNAME => 'Person',
STREET => '1234 Street',
CITY => 'Omaha',
STATE => 'NE',
COUNTRY => 'United States',
ZIP => '12345',
COUNTRYCODE => 'US' );
unless( $resp{ACK} eq 'Success' ) {
croak "dang it...";
}
##
## express checkout
##
$invnum = time;
%resp = $nvp->SetExpressCheckout( AMT => '25.44',
CURRENCYCODE => 'USD',
DESC => 'one widget',
CUSTOM => 'thank you for your money!',
INVNUM => $invnum,
PAYMENTACTION => 'Sale',
RETURNURL => 'http://www.example.com/thankyou.html',
CANCELURL => 'http://www.example.com/sorry.html', );
$token = $resp{TOKEN};
%resp = $pp->GetExpressCheckoutDetails( TOKEN => $token );
$payerid = $resp{PAYERID};
%resp = $pp->DoExpressCheckoutPayment( TOKEN => $token,
AMT => '25.44',
PAYERID => $payerid,
PAYMENTACTION => 'Sale' );DESCRIPTION
Business::PayPal::NVP makes calls to PayPal's NVP ("name-value pair"--a fancy name for HTTP POST queries) API.
Making a call is as simple as creating an NVP object and invoking the PayPal API method with the appropriate arguments.
Consult the PayPal NVP API for parameter names and valid values. Note that you do not need to URI escape your values; this module handles all of the messy HTTP transport issues.
Here is the PayPal NVP API:
https://cms.paypal.com/cms_content/US/en_US/files/developer/PP_NVPAPI_DeveloperGuide.pdf
METHODS
new
Creates a new PayPal connection object. This method is required for all PayPal transactions, but the object may be reused for subsequent transactions.
Parameters:
- branch
-
defaults to 'test'. Set to 'live' if you want to make live transaction queries.
- test
-
sets the test authentication data. Takes a hashref in the following format:
{ user => 'paypal_user_info', pwd => 'paypal_password', sig => 'paypal_signature', version => '53.0', subject => 'some@where.tld' }The version and subject parameters are optional. The version parameter changes the default API version (currently 51.0) for all calls made using this object. The subject parameter is passed as described in the PayPal API documentation (do not use unless you understand what it is for).
- live
-
sets the live authentication data. See 'test' parameter for an example format.
Example:
my $pp = new Business::PayPal::NVP( branch => 'live',
live => { user => 'my.live.paypal.api.username',
pwd => '234089usdfjo283r4jaksdfu934',
sig => SlkaElRakSw34-asdflkj34.sdf', } );errors
Returns a list of the errors encountered during the last transaction, if any.
Example:
$pp->DoDirectPayment(%data)
or do {
warn "Error! " . join("\n", $pp->errors);
};clear_errors
Clears the error list.
All other methods
All other methods are PayPal API calls, exactly as they appear in the manual, with the exception of the METHOD parameter which is inferred from the object's method name (e.g., "DoCapture"). If these methods are not working, check the return value via errors().
Business::PayPal::NVP treats all method calls it does not recognize as PayPal API calls and builds a request for you and sends it using the authentication data you provided in the new() method (either live or test).
You do not need to add the METHOD parameter to any method calls.
If you encounter a method call that requires a higher version number than the default (currently 51.0), you may specify that as part of your call:
%resp = $pp->SomeNewMethod( VERSION => '54.0', %args );This works on a method-by-method basis. To change the default for all method calls, pass in a version parameter when the object is created (see new()).
Examples:
%resp = $pp->DoDirectPayment( PAYMENTACTION => 'Sale',
CREDITCARDTYPE => 'VISA',
etc. );
%resp = $pp->DoCapture( AUTHORIZATIONID => $authid,
AMT => '25.00',
etc. );
%resp = $pp->DoAuthorization( %data );
%resp = $pp->DoReauthorization( %data );
%resp = $pp->DoVoid( %data );
%resp = $pp->SetExpressCheckout( %data );
%resp = $pp->GetExpressCheckout( TOKEN => $token );
%resp = $pp->DoExpressCheckoutPayment( %data );
%resp = %pp->GetTransactionDetails( %data );and so forth. See https://www.paypal.com/en_US/pdf/PP_NVPAPI_DeveloperGuide.pdf for complete API details.
send
This method is supplied to make method calls that don't seem to work using the "automatic" method.
Example:
%resp = $pp->send(METHOD => 'DoDirectPayment', %arguments);EXAMPLES
Examples for each method are scattered throughout the documentation above, as well as in the t directory of this distribution.
TESTING
To run the built-in tests for this module, you'll need to obtain a PayPal developer sandbox account. Once you've done that, create a file in this module's root directory (after you unpack it, the same place where the README file is found) in the following format:
user = your.TEST.api.username.for.paypal.tld
pwd = your.TEST.api.password
sig = your.TEST.api.signatureThe test harness will read this file and try to connect to PayPal's test server to make test API calls.
TROUBLESHOOTING
You may enable the global variable $Debug to turn on some extra debugging. It's not much, but it may help in some cases. For deep debugging, you'll want to uncomment the line at the top of the module:
LWP::Debug qw(+ -conns);Use the errors() method liberally.
Send any additional suggestions to the author.
SEE ALSO
https://www.paypal.com/IntegrationCenter/ic_nvp.html
AUTHOR
Scott Wiersdorf, <scott@perlcode.org>
COPYRIGHT AND LICENSE
Copyright (C) 2008 by Scott Wiersdorf
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.