Business::PayPal::NVP - PayPal NVP API


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

  $token = $resp{TOKEN};

  %resp = $pp->GetExpressCheckoutDetails( TOKEN => $token );

  $payerid = $resp{PAYERID};

  %resp = $pp->DoExpressCheckoutPayment( TOKEN         => $token,
                                         AMT           => '25.44',
                                         PAYERID       => $payerid,
                                         PAYMENTACTION => 'Sale' );


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:



Creates a new PayPal connection object. This method is required for all PayPal transactions, but the object may be reused for subsequent transactions.



defaults to 'test'. Set to 'live' if you want to make live transaction queries.


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).


sets the live authentication data. See 'test' parameter for an example format.


  my $pp = new Business::PayPal::NVP( branch => 'live',
                                      live   => { user => '',
                                                  pwd  => '234089usdfjo283r4jaksdfu934',
                                                  sig  => SlkaElRakSw34-asdflkj34.sdf', } );

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.


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

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


Returns a list of the errors encountered during the last transaction, if any.


    or do {
      warn "Error! " . join("\n", $pp->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()).


  %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 for complete API details.


This method is supplied to make method calls that don't seem to work using the "automatic" method.


  %resp = $pp->send(METHOD => 'DoDirectPayment', %arguments);


Examples for each method are scattered throughout the documentation above, as well as in the t directory of this distribution.


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.


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.




Scott Wiersdorf, <>


Sachin Sebastian, <>


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.