Scott Wiersdorf
and 1 contributors

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',
                                       timeout => 60,
                                     );

  ##
  ## 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://developer.paypal.com/webapps/developer/docs/classic/api/

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 98) 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', } );
ua

sets the user agent used for HTTP requests. Must be an LWP::UserAgent (for now). Useful if you need to set up a proxies, add handlers, or make use of other LWP client features.

Example:

    my $ua = LWP::UserAgent->new();
    $ua->env_proxy(1);

    my $pp = new Business::PayPal::NVP( branch => 'live',
                                        live   => { ... },
                                        ua     => $ua );

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://developer.paypal.com/webapps/developer/docs/classic/api/ 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 the module, the same place where the README file is found) named auth.txt in the following format:

  user = your.TEST.api.username.for.paypal.tld
  pwd  = your.TEST.api.password
  sig  = your.TEST.api.signature

The 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

Business::PayPal::API

AUTHOR

Scott Wiersdorf, <scott@perlcode.org>

CONTRIBUTORS

Sachin Sebastian, <sachinjsk@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2008, 2016 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.