Get Started with PayPal NVP/SOAP APIs

Important: NVP/SOAP is a legacy integration method. We accept new integrations and support existing integrations, but there are newer solutions. If you're starting an integration, we recommend our latest solutions.

PayPal offers a set of application programming interfaces (APIs) that give you the means to incorporate PayPal functionality into your website applications and mobile apps.

This document describes how to make calls to the PayPal NVP/SOAP API operations. Once you understand how to code calls to the PayPal APIs, use the PayPal sandbox to test your PayPal routines, as described in the PayPal sandbox Testing Guide. After you've finished testing your PayPal routines, move your application to the live PayPal environment, as described in Going Live with Your Application.

This guide provides the following sections to get you up and running with the PayPal APIs:

• Creating a PayPal Developer Account
• The Components of an API Request
• Putting a Call Together

PayPal provides two environments that support calls to their API operations:

Sandbox environment

The sandbox is a virtual testing environment where you utilize fictitious user accounts to make calls to the PayPal operations without affecting any real PayPal users or their live PayPal accounts.

Production environment

The production environment is the live environment where the PayPal operation calls you make affect the accounts of real PayPal users.

To make sure you don't accidentally address the wrong environment, each environment uses a different set of API credentials and endpoints.

Creating a PayPal Developer Account

To make calls to the PayPal APIs, you must have a PayPal Premier or PayPal Business account. To create a PayPal account, click the Sign Up link at the top of the main PayPal page, and follow the resulting instructions.

After becoming a PayPal member, use your account log-in information to register as a PayPal Developer:

1. Navigate to the Developer website and click the Log In button at the top of the page.

   The log-in page gives you the option of registering with your current PayPal account credentials, or signing up for a new PayPal Business account.

2. Log in using your PayPal account information (your email address and your password). When you first register on the Developer website, PayPal creates a default sandbox business account. Use the sandbox account details to make test calls.

The Components of an API Request

Each PayPal API call consists of a combination of the following elements:

• API Credentials
• Service Endpoint
• Call Payload
• Request and Response Format Types
• HTTP Headers

The following table gives an overview of these API call elements. See the sections below for more complete descriptions.

API Credentials

You must provide a valid set of API credentials when making calls to PayPal API operations. This allows PayPal to verify the account that's making the calls.

PayPal NVP/SOAP API credentials consist of an API Username, an API Password, and a Signature, and PayPal generates a unique set of credentials for each eligible PayPal account. Your Sandbox accounts and your live PayPal Business or Premier accounts have different sets of API credentials, be sure to use the correct set when testing! On the Developer site, navigate to the Applications > Sandbox accounts page to retrieve the API credentials for your sandbox business accounts.

In addition to the NVP/SOAP API credentials, the Adaptive APIs also make use of an AppID value. To obtain an AppID value for use in the PayPal production environment, submit your application for review, as described in Going Live with Your Application. When testing your Adaptive API calls in the sandbox, use the following static AppID value for the sandbox:

APP-80W284485P519543T

See Creating and Managing NVP/SOAP API Credentials for more on how to generate and maintain the credentials needed to make calls to the live PayPal environment.

Service Endpoint

An endpoint provides the URI of the server that handles your request. Each PayPal service and operation has a unique endpoint. See the PayPal Endpoints page for a list of all the NVP/SOAP API endpoints.

For example, the sandbox endpoint for Express Checkout SetExpressCheckout operation is as follows:

https://api.sandbox.paypal.com/nvp

Use the sandbox endpoints during your application testing phase. After you've finished testing your application in the sandbox, move to the production environment by updating the endpoints in your application so your requests are directed to the correct PayPal production service and operation.

With this, if you're calling an Express Checkout operation with NVP formatting, test in the sandbox with the following endpoint:

https://api-3t.sandbox.paypal.com/nvp

Once your testing is complete, move your application into production by updating your endpoints to the following URI:

https://api-3t.paypal.com/nvp

Don't forget that to go live, you'll also need to update your API credentials to those assigned to your live PayPal account (instead of those assigned to your virtual Sandbox accounts).

Call Payload

Each PayPal API call contains a payload, which is a unique set of input fields that you supply with the request. API operations have both required and optional input fields. Although you can make a basic test call with only the required input fields, your production-level applications will likely make use of optional inputs.

For example, an Express Checkout call requires the following input fields:

• USER—The API User name.
• PWD—The API Password.
• SIGNATURE—The Signature.
• METHOD—The API operation you are addressing.
• VERSION—The version of the API to which you are making your request.
• AMT—The cash amount of the transaction.
• cancelUrl—The URL address to which the user is returned if they cancel the transaction.
• returnUrl—The URL address to which the user is returned when the complete the transaction.

The required fields denote the minimum set of parameters that you can include in the payload of a PayPal API operation request. Below is an example of how this payload would be formatted using name-value pairs:

USER=Your_APIUsername& PWD=Your_APIPassword& SIGNATURE=Your_Signature& METHOD=SetExpressCheckout& VERSION=78& AMT=10& cancelUrl=https://example.com/cancel& returnUrl=https://example.com/success

Request and Response Format Types

The PayPal NVP/SOAP APIs support two types of request and response call formats: SOAP and non-SOAP.

When using SOAP, format the payload using XML within the SOAP envelope and supply any HTTP headers as part of the envelope.

Non-SOAP formatted calls can make use of the following types of payload formats:

x-www-form-urlencoded

Name-Value Pairs (NVP)

XML-RPC

Extensible Markup Language

JSON-RPC

JavaScript object notation (Adaptive APIs only)

How you specify the format of your PayPal operation calls depends on the API you're using. For the Adaptive APIs (Adaptive Payments, Adaptive Accounts, Invoicing and the Permissions Service), specify the request and response formats in the HTTP headers. Other PayPal APIs require that you specify the call formats in the call payload.

HTTP Headers

PayPal has many services and some require that you specify a set of HTTP Headers in your calls. For example, the Adaptive Payments and Adaptive Accounts APIs require the following set of HTTP headers:

Be aware that different PayPal APIs use different sets of HTTP headers (and some don't use any at all). Refer to the Developer documentation for the definitive list of HTTP headers for the PayPal operation(s) you plan to use.

Putting a Call Together

To make a PayPal API call, put together all the components of the call (as described just above) into a SOAP or non-SOAP object, and execute the call.

For example, the following cURL command, wrapped and commented for readability, shows how the call elements are assembled to make a request to the Adaptive Accounts CreateAccount operation:

curl https://svcs.sandbox.paypal.com/AdaptiveAccounts/CreateAccount \
  -s \
  --insecure \
  \
  ## API Credentials \
  -H "X-PAYPAL-SECURITY-USERID: <var>Your_APIUsername</var>" \
  -H "X-PAYPAL-SECURITY-PASSWORD: <var>Your_APIPassword</var>" \
  -H "X-PAYPAL-SECURITY-SIGNATURE: <var>Your_Signature</var>" \
  \
  ## Input and output formats \
  -H "X-PAYPAL-REQUEST-DATA-FORMAT: JSON" \
  -H "X-PAYPAL-RESPONSE-DATA-FORMAT: JSON" \
  \
  ## Static Sandbox app ID \
  -H "X-PAYPAL-APPLICATION-ID: APP-80W284485P519543T" \
  \
  -H "X-PAYPAL-DEVICE-IPADDRESS: 192.0.2.0" \
  -H "X-PAYPAL-SANDBOX-EMAIL-ADDRESS: <var>Your_APICaller-emailAddress</var>" \
  \
  ## Payload, formatted in JSON
  -d '{
        "sandboxEmailAddress": "<var>Sender-emailAddress</var>",
        "accountType": "PERSONAL",
        "name": {
          "firstName": "Lenny",
          "lastName": "Riceman"
        },
        "address": {
          "line1": "123 Main St",
          "city": "Austin",
          "state": "TX",
          "postalCode": "78759",
          "countryCode": "US"
        },
        "citizenshipCountryCode": "US",
        "contactPhoneNumber": "512-555-5555",
        "dateOfBirth": "1968-01-01Z",
        "createAccountWebOptions": {
          "returnUrl": "https://example.com/success.html"
        },
        "currencyCode": "USD",
        "emailAddress": "lr12345@example.com",
        "preferredLanguageCode": "en_US",
        "registrationType": "Web",
        "requestEnvelope": {
          "errorLanguage": "en_US"
        }
      }'

Notice that in cURL commands, HTTP headers are specified with the -H switch.

Learn More

Find more information about making SOAP and Name-Value Pair calls in the following guides:

• PayPal Name-Value Pair API Basics
• PayPal SOAP API Basics

Review the Getting Started Guides listed below to see how to make calls using the two different types of PayPal NVP/SOAP APIs (Express Checkout and Adaptive APIs):

• Express Checkout API Getting Started Guide
• Adaptive Accounts API Getting Started Guide