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.
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 versionNote: After the
METHODparameter, 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:
- 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.
- Invoke additional API operations after receiving the buyer's
permission on PayPal, for example,
The following diagram shows the execution flow between your site and PayPal:
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:
- Name-value pairs are separated by an ampersand (&). For
- 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:
Choose the PayPal API operation you want to use.
Choose the appropriate version.
In most cases, you should use the latest version of the
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:
SIGNATUREin 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:
Specify the API username associated with your
Specify the password associated with the API user name.
If you are using an API signature and not an API certificate,
specify the API signature associated with the API username.
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=merchantEmailAddressNote: 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^ &..."
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.
For example, consider the following NVP string:
NAME=Robert Moore&COMPANY=R. H. Moore & Associates
It is encoded as follows:
Use the following methods to URL-encode or URL-decode your NVP strings:
|Decode||No built-in function. Several implementation examples are available on the Internet.|
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
To identify an element within the list, use the offset from the
beginning of the list, starting with 0 as the first element. For
L_DESC0 is the first line of a description,
is the second line, and so on.
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|
||Sandbox server for use with API signatures; use for testing your API|
||PayPal "live" production server for use with API signatures|
||Sandbox server for use with API certificates; use for testing your API|
||PayPal "live" production server for use with API certificates|
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:
||Acknowledgement status, which is one of
the following values:
||Correlation ID, which uniquely identifies the transaction to PayPal.|
||The date and time that the requested API operation was performed.|
||The version of the API.|
||The sub-version of the API.|
Success, API response fields may not be
returned. An error response has the following general format.
|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.|
Additional pass-through information may appear in the
Consider the following error response:
In this case, the parameter ID is
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.
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.