PayPal Name-Value Pair API Basics

The Name-Value Pair (NVP) API provides parameter-based association between the 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. Name-Value Pair (NVP) describes the format of the request and response messages that you send to and receive from the PayPal API. An example of a name-value pair is FieldName=Value, where FieldName is the name of the PayPal API field and Value is the information that you are passing to or receiving from the PayPal API, such as, VERSION=200.

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 the Payflow 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=API-Operation-Name, to be performed and its version.

    Note: After the METHOD parameter, you can specify the other parameters in any order.

  • API 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 acknowledgment status (ACK) 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, such as the transaction ID.
  • 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. This API operation sets up the return URL to which PayPal redirects your buyer's browser after the buyer completes the payment on the PayPal website. 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 website and PayPal:

Token Usage

Typically, the API operation that sets up a redirection to PayPal (SetExpressCheckout) 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
  • Each value in an NVP string is 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=API-Operation-Name
  2. Choose the appropriate version. In most cases, you should use the latest version of the API operation. VERSION=API-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. If you're calling the API on behalf of a third-party merchant, you must specify the email address on file with PayPal of the third-party merchant or the merchant's account ID (sometimes called Payer ID). SUBJECT=Authorizing-Merchant-Email Or Authorizing-Merchant-Account-ID

    Note: Third-party merchants can look up their merchant ID by logging into https://www.paypal.com, clicking the profile icon (Profile menu) on the top right side of the page and then selecting Profile and settings in the Business Profile menu. (If you do not see a profile icon at the top of the page, click Profile, which appears in the top menu when the My Account tab is selected.) Click My business info on the left, and the Merchant account ID is displayed in the list of profile items on the right.

    Typically, a merchant grants third-party permissions to a shopping cart, so the shopping cart can call the API on the merchant's behalf. The merchant must have previously granted you permission to execute the API operation.

Specifying Credentials Using cURL

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

curl https://api-3t.sandbox.paypal.com/nvp
  --insecure \
  -d METHOD=name \
  -d VERSION=XX.0 \
  -d USER=API-Username \
  -d PWD=API-Password \
  -d SIGNATURE=API-Signature \
  -d ...

Note: This example does not establish a secure connection and should not be used in the live environment.

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

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

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, since in some cases you can submit more than one payment in a single request, PAYMENTREQUEST_0_DESC is the description of the first payment in a request, PAYMENTREQUEST_0_DESC, is the description of the second payment in the request, and so on.

Additionally, you can pass lists within lists, which also use an offset that starts with 0 as the first element. For example, L_PAYMENTREQUEST_0_DESC0 is the description of the first item in the first payment.

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 "testing" server for use with API signature credentials.
https://api-3t.paypal.com/nvp PayPal "live" production server for use with API signature credentials.
https://api.sandbox.paypal.com/nvp Sandbox "testing" server for use with API certificate credentials.
https://api.paypal.com/nvp PayPal "live" production server for use with API certificate credentials.

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 CorrelationID returned in the response message, which identifies the PayPal application that processed the request 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 Acknowledgment status, which is one of the following values:
  • Success — A successful operation.
  • SuccessWithWarning — A successful operation; however, there are messages returned in the response that you should examine.
  • Failure — The operation failed; the response also contains one or more error messages explaining the failure.
  • FailureWithWarning — The operation failed and 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 in UTC/GMT format.
VERSION The version of the API.
BUILD The sub-version of the API.

Error Responses

If the ACK value is not Success, the payment or desired action may not go through.

Possible values of the ACK response field are the following:

  • Success — The request was successful.
  • SuccessWithWarning — The request was successful but a warning error code was also returned.
  • Failure — The API request failed. See error messages for details.
  • FailureWithWarning — The API request failed and additional warning messages were returned.

An error response has the following general format.

Format of an Error Response
Response Fields on Error
ACK=Failure&TIMESTAMP=Date-And-Time-Of-Response&
CORRELATIONID=debuggingToken&VERSION=API-Version&
BUILD=buildNumber&L_ERRORCODE0=Error-Code&
L_SHORTMESSAGE0=Short-Error-Message&
L_LONGMESSAGE0=Long-Error-Message&
L_SEVERITYCODE0=Severity-Code
Multiple errors can be returned. Each set of errors has a different numeric suffix in the field name, 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 from the PayPal NVP API must be URL 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 via the HTTP protocol so that it can be displayed properly. Most programming languages provide a way to URL decode strings.