API Basics

PayPal offers REST APIs for new integrations. These APIs use HTTP methods, a RESTful endpoint structure, the OAuth 2.0 protocol, and JSON-formatted payloads. Use REST APIs to incorporate PayPal functionality into your web and mobile apps.

Note: PayPal offers Name-Value Pair (NVP) and Simple Object Access Protocol (SOAP) APIs for legacy integrations. These APIs support NVP- and SOAP-formatted payloads, while some APIs also support JSON-formatted payloads.

API classification

PayPal classifies APIs as live, limited-release, or deprecated.

Live The current docs. Operational and available to new subscribers in production. Fully supported.
Limited release Operational but available only to a specific market. Fully supported.
Deprecated Archived docs. Operational and available to existing subscribers but not available to new subscribers. Fully supported, including backward-compatible bug fixes.

OAuth 2.0 authorization protocol

The PayPal REST APIs use the OAuth 2.0 protocol to authorize calls. OAuth is an open standard that many companies use to provide secure access to protected resources.

When you create a REST API app, PayPal generates a set of OAuth 2.0 client ID and secret credentials for the sandbox and live environments. When you make a get an access token call, set the Authorization header to these credentials for your environment.

In exchange for these credentials, the PayPal authorization server returns your access token in the access_token field:

  "scope": "scope",
  "access_token": "Access-Token",
  "token_type": "Bearer",
  "app_id": "APP-80W284485P519543T",
  "expires_in": 31349,
  "nonce": "nonce"

Include this bearer token in the Authorization header with the Bearer authentication scheme in REST API calls to prove your identity and access protected resources. This sample request includes a bearer token:

curl -v -X GET https://api.sandbox.paypal.com/v1/invoicing/invoices?page=3&page_size=4&total_count_required=true \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token"

Access tokens have a finite lifetime. The expires_in field contains the number of seconds after which the token expires. For example, an access token with an expiry value of 3600 expires in one hour from when the response was generated.

To detect when an access token expires, write code to either:

  • Keep track of the expires_in value in the token response.
  • Handle the HTTP 401 Unauthorized status code. The API endpoint issues this status code when it detects an expired token.

Re-use the access token until it expires. Then, get a new token.

Developer process

Follow these steps to develop an a REST API app:

  1. Set up your development environment. See Get Started.

  2. Learn how to integrate with PayPal products and solutions. See the Docs Catalog.

  3. Create REST API apps for testing, and go live with your apps. See Manage Your Apps.

Support, docs, and resources