This chapter describes the PayPal Name-Value Pair (NVP) API at a high level and contains the following sections:The PayPal NVP API is a simple programmatic interface that allows you, the merchant, to access PayPal’s business functionality to:
l Capture payments previously authorized through Express Checkout, Direct Payment, or Website Payments Standard.The PayPal NVP API makes it easy to add PayPal to your web application. You construct an NVP string and post it to the PayPal server using HTTPS. PayPal posts back a reponse in NVP format.You can integrate directly with the PayPal NVP API using the programming language of your choice. This is the most straightforward and flexible approach. You can download web samples that show how to integrate directly using Classic ASP, PHP, and ColdFusion.You can integrate with the NVP API using a software development kit (SDK). SDKs are provided for Java and ASP.NET. The SDKs provide simple functions for integrating with the NVP API.For details about the PayPal NVP SDK, see Appendix D, “The Java SDK” or Appendix E, “The ASP.NET SDK.”To help you get started with the PayPal NVP API, samples are provided at https://www.paypal.com/IntegrationCenter/ic_nvp.html. Using the samples, you can send API calls to the PayPal Sandbox test environment.During application development, your application communicates with the PayPal Sandbox test environment. The following section, “Taking Your Application Live”, describes how to move your application to the live PayPal environment.
Note: Your NVP API implementation usually runs in a web application. You can write your own application or use one of the samples as a starting point.To access the PayPal API, you need API credentials, either an API signature or API certificate, that identify you.Use the following sample API signature and password in your sample programs that run in the PayPal Sandbox test environment.
Table 1.1 Create an NVP request string and post it to PayPal sandbox server. Add code to your web application to do the following tasks:
1. URL-encode the name and value parameters in the request to ensure correct transmission of all characters. This is described in “URL-Encoding”.
2. Construct the NVP API request string as described in “Request Format”. The NVP format is described in “NVP Format”.PayPal processes your request and posts back a reponse in NVP format. Add code to your web application to do the following tasks:After you have finished coding and testing your application, deploy your application to the live PayPal server using your PayPal business account and API credentials for that account.When you are ready to deploy your application to the live PayPal server, create a PayPal business account on www.paypal.com.To use the APIs, you need a set of credentials to identify yourself to PayPal. Create an API signature for your business account.For instructions on setting up API credentials for the business account, go to https://www.paypal.com/IntegrationCenter/ic_certificate.html.
IMPORTANT: If you are using API signature, you must protect the API signature values in your implementation. Consider storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user that executes your ecommerce application can access it.The sample code does not store these values securely. The sample code should never be used in production.In your application, change the following items from the PayPal Sandbox values to the live PayPal server values:When you use the PayPal NVP API, you post an NVP request to PayPal, and PayPal posts back an NVP response.The request and response are in URL-encoded format, which is defined by the Worldwide Web Consortium (W3C). URL is defined as part of the URI specification. Find out more about URI at http://www.w3.org/Addressing/.NVP is a way of specifying names and values in a string. NVP is the informal name for the query in the URI specification. The NVP string is appended to the URL.The request and response are URL-encoded. URL-encoding ensures that you can transmit special characters, characters that are not allowed in a URL, and characters that have special meaning in a URL, such as the equal sign and ampersand. For example, the following NVP string:
Table 1.2 System.Web.HttpUtility.UrlEncode(buffer, Encoding.Default) System.Web.HttpUtility.UrlDecode(buffer, Encoding.Default) Classic ASP Each NVP request consists of required and optional parameters and their values. Parameter names are not case sensitive. The examples in this document use UPPERCASE for parameter names and divide the parameters into required security parameters and body parameters.
Table 1.3 Required Security Parameters Body Parameters In practice, you need to concatenate all parameters and values into a single URL-encoded string. After the METHOD parameter, you can specify the parameters in any order.
Email address of a PayPal account that has granted you permission to make this call.
IMPORTANT: You must protect the values for USER, PWD, and SIGNATURE in your implementation. Consider storing these values in a secure location other than your web server document root and setting the file permissions so that only the system user that executes your ecommerce application can access it.The sample code does not store these values securely. The sample code should never be used in production.You may see sample code where these values are stored in an HTML form. The following is an example of what you should NOT do in production:The request body must contain the name of the API method in the METHOD parameter. In addition, each method has required and optional parameters:All API methods and their parameters are detailed in Appendix A, “NVP API Method and Field Reference.” Examples of use are in Chapter 2, “Charging a Credit Card Using DoDirectPayment,” Chapter 3, “Accepting PayPal in Express Checkout,” and Chapter 6, “Back-Office Administration.”Examples of use are in Chapter 3, “Accepting PayPal in Express Checkout.”A response from the PayPal servers is a URL-encoded name-value pair string, just like the request, except it has the following general format.
Table 1.5 Success Response Fields The examples show the successful response header fields like this: API Response Fields Each response includes the ACK field. If the ACK field’s value is Success or SuccessWithWarning, you should process the API response fields. In a successful response, you can ignore all fields up to and including the BUILD field. The important fields begin after the BUILD field.The possible successful response fields for each method are detailed in Appendix A, “NVP API Method and Field Reference.” What you do with the fields depends on the particular API method you are calling, such as filling-in a FORM for your user, updating your database, and so on.If the ACK value is Error or Warning, API response fields are not returned. An error response has the following general format.
Table 1.6 Response Fields on Error Multiple errors can be returned. Each set of errors has a different numeric suffix, starting with 0 and incremented by one for each error.For possible causes of errors and how to correct them, see the explanation of the specific error code, short message, and long message in Appendix B, “Error Message Reference.”
Table 1.7 Your web application posts the URL-encoded NVP string over an HTTPS connection to one of the PayPal API servers. PayPal provides a live server and a Sandbox server that allows you to process transactions in a test environment.Sandbox: https://api-3t.sandbox.paypal.com/nvpLive: https://api-3t.paypal.com/nvpSandbox: https://api.sandbox.paypal.com/nvpLive: https://api.paypal.com/nvp