PayPal Name-Value Pair API Basics

The Name-Value Pair (NVP) API provides parameter-based association between request and response fields of a message and their values. The request message is sent from your website by the API, and a response message is returned by PayPal using a client-server model in which your site is a client of the PayPal server.

Note: The PayFlow API also uses name-value pairs to provide parameter-based association between request and response fields of a message and their values; however, the PayFlow API is not the same as the NVP API; for more information about the PayFlow API, see Gateway Developer Guide and Reference.

PayPal API Client-Server Architecture

The PayPal API uses a client-server model in which your website is a client of the PayPal server.

A page on your website initiates an action on a PayPal API server by sending a request to the server. The PayPal server responds with a confirmation that the requested action was taken or indicates that an error occurred. The response might also contain additional information related to the request. The following diagram shows the basic request-response mechanism.



For example, you might want to obtain the buyer's shipping address from PayPal. You can initiate a request specifying an API operation to obtain buyer details. The response from the PayPal API server contains information about whether the request was successful. If the operation succeeds, the response contains the requested information. In this case, the response contains the buyer's shipping address. If the operation fails, the response contains one or more error messages.

PayPal Name-Value Pair API Requests and Responses

To perform a PayPal NVP API operation, you send an NVP-formatted request to a PayPal NVP server and interpret the response.

In the following diagram, your website generates a request. The request is executed on a PayPal server and the response is returned to your site.



The request identifies:

  • The name of the API operation, specified by METHOD=name, to be performed and its version
    Note: After the METHOD parameter, you can specify the parameters in any order.
  • Credentials that identify the PayPal account making the request
  • Request-specific information that controls the API operation to be performed

A PayPal API server performs the operation and returns a response. The response contains:

  • An acknowledgement status that indicates whether the operation was a success or failure and whether any warning messages were returned
  • Information that can be used by PayPal to track execution of the API operation
  • Response-specific information required to fulfill the request

UTF-8 Character Encoding

The PayPal API assumes that all data in requests is in Unicode, specifically, the Unicode (or UCS) Transformation Format, 8-bit encoding form (UTF-8).

In responses, the API always returns data in UTF-8.

Multiple API Operations

Some of the features, such as Express Checkout, require you to call multiple API operations.

Typically, these features require you to:

  1. Invoke an API operation, such as SetExpressCheckout, that sets up the return URL to which PayPal redirects your buyer's browser after the buyer finishes on PayPal. Other setup actions also can be performed by this API operation.
  2. Invoke additional API operations after receiving the buyer's permission on PayPal, for example, GetExpressCheckoutDetails or DoExpressCheckoutPayment.

The following diagram shows the execution flow between your site and PayPal:



Token Usage

Typically, the API operation that sets up a redirection to PayPal returns a token. This token is passed as a parameter in the redirect to PayPal. The token also might be required in related API operations.

NVP Format

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.

An NVP string conforms to the following guidelines:

  • The name is separated from the value by an equal sign (=). For example:
    FIRSTNAME=Robert
    
  • Name-value pairs are separated by an ampersand (&). For example:
    FIRSTNAME=Robert&MIDDLENAME=Herbert&LASTNAME=Moore
    
  • The values for each value in an NVP string are URL-encoded.

Creating an NVP Request

The Name-Value Pair request format specifies the API operation to perform, credentials that authorize PayPal to access your account, and fields containing additional information to be used in the request.

Specifying the PayPal API Operation

For the NVP version of the PayPal API, you must specify the name of the PayPal API operation to execute in each request along with the version of the API operation.

The following diagram shows the API operation part of an NVP request:



A method specifies the PayPal operation you want to execute, and each method is associated with a version. Together, the method and version define the exact behavior of the API operation. Typically, the behavior of an API operation does not change between versions; however, you should carefully retest your code whenever you change a version.

To specify a method and version number:

  1. Choose the PayPal API operation you want to use. METHOD=operation
  2. Choose the appropriate version. In most cases, you should use the latest version of the API operation. VERSION=version_number

Specifying an API Credential Using Signatures

You must specify API credentials in each request to execute a PayPal API operation. You can use either a signature or a certificate, but not both.

When you execute a PayPal API operation, you use credentials, such as a signature, to authenticate that you are requesting the API operation. The following diagram shows the API credentials part of an NVP request:



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.

To enable PayPal to authenticate your request:

  1. Specify the API username associated with your account. USER=API_username
  2. Specify the password associated with the API user name. PWD=API_password
  3. If you are using an API signature and not an API certificate, specify the API signature associated with the API username. SIGNATURE=API_signature
  4. Optionally, you can specify the email address on file with PayPal of the third-party merchant on whose behalf you are calling the API operation. SUBJECT=merchantEmailAddress
    Note: Typically, a merchant grants third-party permissions to a shopping cart. The merchant previously must have given you permission to execute the API operation.

Specifying Credentials Using cURL

The following example shows one way to specify a signature using cURL:

curl --insecure https://api-3t.sandbox.paypal.com/nvp -d ^
"METHOD=name^ &VERSION=XX.0^ &USER=API_username^ &PWD=API_password^ &SIGNATURE=API_signature^ &..."
Note: This example does not establish a secure connection and should not be used live on paypal.com.

URL Encoding

All requests to execute PayPal API operations sent using HTTP must be URL-encoded. The 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.

The PayPal NVP API uses the HTTP protocol to send requests and receive responses from a PayPal API server. You must encode all data sent using the HTTP protocol because data that is not encoded could be misinterpreted as part of the HTTP protocol instead of part of the request. Most programming languages provide a way to encode strings in this way. You should consistently URL-encode the complete API request; otherwise, you may find that unanticipated data causes an error.

Note: An HTTP form is automatically URL-encoded by most browsers.

For example, consider the following NVP string:

NAME=Robert Moore&COMPANY=R. H. Moore & Associates

It is encoded as follows:

NAME=Robert+Moore&COMPANY=R.+H.+Moore+%26+Associates

Use the following methods to URL-encode or URL-decode your NVP strings:

Table 1. Encoding and decoding methods for URLs
Language Method
ASP.NET Encode System.Web.HttpUtility.UrlEncode(buffer, Encoding.Default)
Decode System.Web.HttpUtility.UrlDecode(buffer, Encoding.Default)
Classic ASP Encode Server.URLEncode
Decode No built-in function. Several implementation examples are available on the Internet.
Java Encode java.net.URLEncoder.encode
Decode java.net.URLDecoder.decode
PHP Encode urlencode()
Decode urldecode()
ColdFusion Encode URLEncodedFormatstring [, charset]
Decode URLDecodeurlEncodedString[, charset])

List Syntax for Name-Value Pairs

The PayPal API uses a special syntax for NVP fields defined as lists.

The NVP interface to the PayPal API requires a unique name for each field. In the API, lists are prefixed by L_.

To identify an element within the list, use the offset from the beginning of the list, starting with 0 as the first element. For example, L_DESC0 is the first line of a description, L_DESC1, is the second line, and so on.

Note: Not all lists follow the L_ prefix convention; however, all lists start with 0 as the first element.

Executing NVP API Operations

You execute a PayPal NVP API operation by submitting an HTTPS POST request to a PayPal API server, or by using cURL or another mechanism to provide secure access between the buyer's browser and the PayPal API server. For example, you might implement a system in which the buyer's browser remains a client of your server and your server becomes a client of the PayPal API server.

Specifying a PayPal Server

You execute a PayPal API operation by submitting the request to a PayPal API server.

To execute a PayPal NVP API operation, submit the request to one of the following end points:

Server end point Description
https://api-3t.sandbox.paypal.com/nvp Sandbox server for use with API signatures; use for testing your API
https://api-3t.paypal.com/nvp PayPal "live" production server for use with API signatures
https://api.sandbox.paypal.com/nvp Sandbox server for use with API certificates; use for testing your API
https://api.paypal.com/nvp PayPal "live" production server for use with API certificates
Note: You must use different API credentials for each server end point. Typically, you obtain API credentials when you test in the Sandbox and then obtain another set of credentials for the production server. You must change each API request to use the new credentials when you go live.

Logging API Operations

You should log basic information from the request and response messages of each PayPal API operation you execute. You must log the Correlation ID from the response message, which identifies the API operation to PayPal and must be provided to Merchant Technical Support if you need their assistance with a specific transaction.

All responses to PayPal API operations contain information that may be useful for debugging purposes. In addition to logging the Correlation ID from the response message, you can log other information, such as the transaction ID and timestamp, to enable you to review a transaction on the PayPal website or through the API. You could implement a scheme that logs the entire request and response in a "verbose" mode; however, you should never log the password from a request.

Responding to an NVP Response

The Name-Value Pair response consists of the answer to the request as well as common fields that identify the API operation and how it was executed.

The following diagram shows fields in the response to a PayPal NVP API operation:



Common Response Fields

The PayPal API always returns common fields in addition to fields that are specific to the requested PayPal API operation.

A PayPal API response includes the following fields:

Field Description
ACK Acknowledgement status, which is one of the following values:
  • Success indicates a successful operation.
  • SuccessWithWarning indicates a successful operation; however, there are messages returned in the response that you should examine.
  • Failure indicates the operation failed; the response also contains one or more error messages explaining the failure.
  • FailureWithWarning indicates that the operation failed and that there are messages returned in the response that you should examine.
CORRELATIONID Correlation ID, which uniquely identifies the transaction to PayPal.
TIMESTAMP The date and time that the requested API operation was performed.
VERSION The version of the API.
BUILD The sub-version of the API.

Error Responses

If the ACK value is not Success, API response fields may not be returned. An error response has the following general format.

Table 2. Format of an Error Response
Response Fields on Error ACK=notSuccess&TIMESTAMP=date/timeOfResponse& CORRELATIONID=debuggingToken&VERSION=VersionNo& BUILD=buildNumber&L_ERRORCODE0=errorCode& L_SHORTMESSAGE0=shortMessage& L_LONGMESSAGE0=longMessage& L_SEVERITYCODE0=severityCode Multiple errors can be returned. Each set of errors has a different numeric suffix, starting with 0 and incremented by one for each error.

Additional pass-through information may appear in the L_ERRORPARAMIDn and L_ERRORPARAMVALUEn fields.

Consider the following error response:

TIMESTAMP=2011%2d11%2d15T20%3a27%3a02Z&CORRELATIONID=5be53331d9700&ACK=Failure&VERSION=78%2e0&BUILD=000000&L_ERRORCODE0=15005&L_SHORTMESSAGE0=Processor%20Decline&L_LONGMESSAGE0=This%20transaction%20cannot%20be%20processed%2e&L_SEVERITYCODE0=Error&L_ERRORPARAMID0=ProcessorResponse&L_ERRORPARAMVALUE0=0051&AMT=10%2e40&CURRENCYCODE=USD&AVSCODE=X&CVV2MATCH=M

In this case, the parameter ID is ProcessorResponse, which indicates an error response by a credit or debit card processor. The value contains the processor-specific error. These values are not set by PayPal; rather, they are passed through from the source.

Note: PayPal only passes selected values in the L_ERRORPARAMIDn and L_ERRORPARAMVALUEn fields.

URL Decoding

All responses to HTTP POST operations used by the PayPal NVP API must be decoded.

The PayPal NVP API uses the HTTP protocol to send requests and receive responses from a PayPal API server. You must decode all data returned using the HTTP protocol so that it can be displayed properly. Most programming languages provide a way to decode strings.