PayPal NVP 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. 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 pass to or receive from the PayPal API, such as, VERSION=200.

PayPal API client-server architecture

The PayPal API uses a client-server model. 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 get the customer's shipping address from PayPal. You can initiate an API request to get customer 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 customer's shipping address. If the operation fails, the response contains one or more error messages.

PayPal Name-Value Pair API requests and responses

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

In this diagram, your website generates a request. The request runs 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 completes the operation and returns a response.

The response contains:

• An acknowledgment (ACK) status that indicates whether the operation succeeded or failed 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 request data is in Universal Coded Character Set (UCS) Transformation Format – 8-bit encoding form (UTF-8).

The API always returns data in UTF-8.

Multiple API operations

Some features, such as Express Checkout, require that 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 customer'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 customer'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 specifies 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 these 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.

Create 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.

Specify 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

Use API signature credentials

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:

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

Specify credentials with cURL

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

1curl https://api-3t.sandbox.paypal.com/nvp \
2    --insecure \
3    -d METHOD=name \
4    -d VERSION=XX.0 \
5    -d USER=<var>API-Username</var> \
6    -d PWD=<var>API-Password</var> \
7    -d SIGNATURE=<var>API-Signature</var> \
8    -d ...

URL encoding

You must URL-encode all HTTP requests to execute PayPal API operations. The encoding ensures that you can transmit:

• Special characters.
• Characters that are not allowed in a URL.
• 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 to and receive responses from a PayPal API server.

You must encode all data sent using the HTTP protocol because data that is not encoded can 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 might find that unanticipated data causes an error.

For example, this NVP string:

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

Is encoded, as follows:

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

Encode and decode methods for URLs

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

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, 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_1_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.

Execute 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.

Specify 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 endpoints:

Log API operations

You must 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.

Respond 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:

Error responses

If the ACK value is not Success, the payment or desired action might fail.

The value of the ACK response is:

• 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.

Error response format

An error response has this format:

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

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

In this 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

The parameter ID is ProcessorResponse, which indicates an error response by a credit or debit card processor.

The value contains the processor-specific error.

PayPal does not set these values. Instead, these values are passed through from the source.

URL decoding

You must URL-decode all responses to HTTP POST operations from the PayPal NVP API

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 through the HTTP protocol so that it can be displayed properly. Most programming languages provide a way to URL-decode strings.