Get Started

API

Last updated: Sept 18th, 6:24pm

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:

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:

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

Call Element Description
API Credentials Many API calls require a set of values to authenticate you as the owner of a PayPal account. The NVP/SOAP API credentials are assigned to your PayPal account and consist of an API Username, an API Password, and a Signature. Some API calls (such as those in the Adaptive APIs) also require an AppID value.
Service Endpoint An API request can be sent to either the sandbox endpoint or the Production endpoint. The endpoint you use depends on several conditions, such as the API operation you're calling, the environment you're addressing, and the format of your call.
Call Payload Each PayPal API call has both required and optional input fields that detail the specifics of the request. Together, these input fields are termed the call payload.
Call Formats PayPal supports calls made using both SOAP and non-SOAP formats. In addition, call payloads can be formatted in JSON and NVP.
HTTP Headers PayPal API operations require you provide specific HTTP headers with your requests. The headers specify authentication credentials, the call request and response formats, and other information. For example, when calling either the Adaptive Payments or Adaptive Accounts APIs, you need to specify your App ID in the X-PAYPAL-APPLICATION-ID header. You specify the format of the request and response using two separate headers, X-PAYPAL-REQUEST-DATA-FORMAT and X-PAYPAL-RESPONSE-DATA-FORMAT.

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:

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:

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:

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

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:

HTTP Header Description
X-PAYPAL-SECURITY-USERID The API user name. This is one of the API credentials assigned to your account.
X-PAYPAL-SECURITY-PASSWORD The API password. This is one of the API credentials assigned to your account.
X-PAYPAL-SECURITY-SIGNATURE The API signature. This is one of the API credentials assigned to your account.
X-PAYPAL-APPLICATION-ID The sandbox contains a unique and static App ID (APP-80W284485P519543T). When you move an application into production, PayPal assigns your application a custom App ID that you need to use to key your application with the production servers.
X-PAYPAL-REQUEST-DATA-FORMAT The payload format for the request.
X-PAYPAL-RESPONSE-DATA-FORMAT The payload format for the response.

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: 

    1curl https://svcs.sandbox.paypal.com/AdaptiveAccounts/CreateAccount \
    2  -s \
    3  --insecure \
    4  \
    5  ## API Credentials \
    6  -H "X-PAYPAL-SECURITY-USERID: <var>Your_APIUsername</var>" \
    7  -H "X-PAYPAL-SECURITY-PASSWORD: <var>Your_APIPassword</var>" \
    8  -H "X-PAYPAL-SECURITY-SIGNATURE: <var>Your_Signature</var>" \
    9  \
    10  ## Input and output formats \
    11  -H "X-PAYPAL-REQUEST-DATA-FORMAT: JSON" \
    12  -H "X-PAYPAL-RESPONSE-DATA-FORMAT: JSON" \
    13  \
    14  ## Static Sandbox app ID \
    15  -H "X-PAYPAL-APPLICATION-ID: APP-80W284485P519543T" \
    16  \
    17  -H "X-PAYPAL-DEVICE-IPADDRESS: 192.0.2.0" \
    18  -H "X-PAYPAL-SANDBOX-EMAIL-ADDRESS: <var>Your_APICaller-emailAddress</var>" \
    19  \
    20  ## Payload, formatted in JSON
    21  -d '{
    22        "sandboxEmailAddress": "<var>Sender-emailAddress</var>",
    23        "accountType": "PERSONAL",
    24        "name": {
    25          "firstName": "Lenny",
    26          "lastName": "Riceman"
    27        },
    28        "address": {
    29          "line1": "123 Main St",
    30          "city": "Austin",
    31          "state": "TX",
    32          "postalCode": "78759",
    33          "countryCode": "US"
    34        },
    35        "citizenshipCountryCode": "US",
    36        "contactPhoneNumber": "512-555-5555",
    37        "dateOfBirth": "1968-01-01Z",
    38        "createAccountWebOptions": {
    39          "returnUrl": "https://example.com/success.html"
    40        },
    41        "currencyCode": "USD",
    42        "emailAddress": "lr12345@example.com",
    43        "preferredLanguageCode": "en_US",
    44        "registrationType": "Web",
    45        "requestEnvelope": {
    46          "errorLanguage": "en_US"
    47        }
    48      }'

    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:

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

    ReferencePayPal.comPrivacyCookiesSupportLegalContact

    If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more