PayPal NVP - Encore Systems

.NET Class Library for PayPal™ NVP API

What is included in the download?

The download includes the PayPal NVP API class library .dll file to reference in your project, as well as a Visual Studio project for this complete demo site.

To run this demo on your local machine, unzip the download and open the Visual Studio solution in the PayPalNvpMvcDemo folder.

How do I install this library?

In your project, add a reference to the "Encore.PayPal.Nvp.dll" file.

Add the "encore.PayPal.Nvp" config section to your web.config file, and set the environment, username, password, and signature attributes. Here is an example:

<configuration>
  <configSections>
      <section name="encore.PayPal.Nvp" type="Encore.PayPal.Nvp.Configuration, Encore.PayPal.Nvp" requirePermission="false"/>
  </configSections>
  <encore.PayPal.Nvp
      environment="(Live or Sandbox)"
      username="(Your PayPal API username)"
      password="(Your PayPal API password)"
      signature="(Your PayPal API signature)">
  </encore.PayPal.Nvp>
...

Here is a complete list of optional configuration properties. They are already defaulted to the values shown here, and it is neither necessary, nor recommended to include them unless you need to override the default.

<encore.PayPal.Nvp
    environment="Live"
    version="124.0" 
    api3tURL="https://api-3t.paypal.com/nvp/"
    apiaaURL="https://api.paypal.com/nvp/"
    paypalURL="https://www.paypal.com/"
    delegateClass=""
    delegateMethod=""
    useCertificate="false"
    useEncryption="false"
    encryptionKey=""
    username=""
    password=""
    signature=""
    subject=""
    keyPassword=""
    certificate=""
    locale="US"
    keepAlive="true">
</encore.PayPal.Nvp>

How do I upgrade from the previous version of this library?

Verify that your project is targeting .NET 4.5.1 or later. Upgrade the project if necessary.

Remove the projet reference to the old "Encore.PayPal.Nvp.dll" file, and add a reference to the new "Encore.PayPal.Nvp.dll" file.

Remove the "licensedTo" and "licenseKey" attributes from the "encore.PayPal" section of your web.config file. A license is no longer required for this library.

Why am I getting Error 10501 Invalid Merchant Configuration?

This means that Website Payments Pro is not enabled for your account. You need to accept the billing agreement, or contact PayPal customer service to have your account configured correctly.

Why am I getting Error 10002 Security header is not valid?

This means something is incorrect with your API credentials. Usually this is because you are attempting to use Live credentials in the Sandbox, or Sandbox credentials in the Live environment.

It could be an invalid password or signature (make sure there are no extra spaces if you copy/pasted from your PayPal account page).

Which PayPal API calls are supported by this library?

NvpAddressVerify returns the status of a PayPal account address, including street and zip code match results. (requires special permission)

NvpBillOutstandingAmount bills any balance due on a recurring payments profile.

NvpCreateBillingAgreement returns a billing agreement ID that may be used to make reference transactions against a PayPal account. (undocumented, needs special permission)

NvpCreateRecurringPaymentsProfile creates a recurring payments profile allowing automatic periodic billing.

NvpDoAuthorization is your request to authorize a customer order that can be fulfilled within 29 days.

NvpDoCapture is your request to completely or partially settle an order, an authorization, or reauthorization.

NvpDoDirectPayment charges or authorizes a credit card.

NvpDoExpressCheckoutPayment obtains payment through Express Checkout for a final sale or requests authorization for later capture of payment.

NvpDoNonReferencedCredit makes a non-referenced credit to a customer’s credit card.

NvpDoReauthorization reauthorizes a previously authorized a transaction and that has passed its settlement period.

NvpDoReferenceTransaction makes a payment based on the information provided in a previous Direct Payment, avoiding the need to provide any buyer information.

NvpDoVoid voids an order or an authorization.

NvpGetBalance returns the PayPal account balance of the account whose API credentials are used for the call.

NvpGetBillingAgreementCustomerDetails returns information about the customer, including name and address on file with PayPal.

NvpGetExpressCheckoutDetails returns information about the customer, including name and address on file with PayPal.

NvpGetRecurringPaymentsProfileDetails

returns the details of a recurring payments profile.

NvpGetTransactionDetails gets details about a transaction.

NvpManagePendingTransactionStatus accepts or denies a pending transaction. (undocumented, untested, needs special permission)

NvpManageRecurringPaymentsProfileStatus allows a recurring payment profile to be cancelled, suspended, or reactivated.

NvpMassPay processes payments en masse to up to 250 different recipients.

NvpRefundTransaction refunds a payment.

NvpSetCustomerBillingAgreement indicates to PayPal that you are using Express Checkout to create billing agreements for your customer.

NvpSetExpressCheckout indicates to PayPal that you are using Express Checkout to obtain payment from your customer.

NvpTransactionSearch searches transaction history.

NvpUpdateRecurringPaymentsProfile allows modification of the terms of a recurring payments profile.

What other tools are provided by this library?

Special Classes, Constants, and Binding Sources are provided to simplify building your payment solution.

NvpCredentialsDelegate The developer can define a function that takes no parameters and has return type NvpCredentials, and then pass that function to any API call instead of setting credentials individually. This can increase security by passing the API credentials from an encrypted store of the developer’s choice. The delegate function may also be declared in the application’s configuration file to make this a global setting.

NvpConfig is a static class that returns all properties defined in the encore.PayPal.Nvp configuration section of the application’s configuration file. Default values are returned for any property not set in the configuration file.

NvpMonthCodeType encapsulates a list of calendar month constants, including integer value, short name, and long name. Includes a BindingSource property to allow binding directly to DropDownList objects, and a Get() member to allow binding to an ObjectDataSource.

NvpYearCodeType encapsulates a list of calendar year constants from the current year through current year plus eleven. Includes a BindingSource property to allow binding directly to DropDownList objects, and a Get() member to allow binding to an ObjectDataSource.

NvpStateCodeType encapsulates a list of states and provinces, including name and two-character code. Includes a BindingSource property to allow binding directly to DropDownList objects, and a Get() member to allow binding to an ObjectDataSource.

NvpCountryCodeType encapsulates a list of countries, including name and two-character code. Includes a BindingSource property to allow binding directly to DropDownList objects, and a Get() member to allow binding to an ObjectDataSource.

NvpLocaleCodeType encapsulates a list of countries for which PayPal Express Checkout pages include culture settings. Includes name and two-character code, a BindingSource property to allow binding directly to DropDownList objects, and a Get() member to allow binding to an ObjectDataSource.

NvpCurrencyCodeType encapsulates a list of currencies accepted by PayPal, including name and three-character code. Includes a BindingSource property to allow binding directly to DropDownList objects, and a Get() member to allow binding to an ObjectDataSource.

Unlike the SOAP API, the NVP API doesn’t automatically provide enumerations for all of the special PayPal types such as BillingCodeType, ChannelType, etc. The Encore Class Library includes a class of constants for each of these special PayPal types. These Encore classes also have a Get() method and a BindingSource property that allows the developer to bind these lists to ObjectDataSources and DropDownLists. Following are enumeration classes included in the class library.