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.

Developer process

Follow these steps to develop an a REST API app:

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

  2. To include PayPal products and solutions in your integration, see the API references and integration guides in the Docs Catalog.

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

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 sandbox or live REST API app, PayPal generates a set of OAuth 2.0 client ID and secret credentials for the sandbox or live environment. When you make a get an access token call, set the Authorization header to these credentials for the environment in which you're making the call.

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.

API idempotency

You can make idempotent calls any number of times without concern that the server creates or completes an action on a resource more than once. You can retry idempotent calls that fail with network timeouts or the HTTP 500 status code for as long as the server stores the ID. Idempotency enables you to correlate request payloads with response payloads, eliminate duplicate requests, and retry failed requests or requests with unclear responses.

To enforce idempotency on REST API POST calls, use the PayPal-Request-Id request header, which contains a unique user-generated ID that the server stores for a period of time.

Note: Not all APIs support this header. To determine whether your API supports it and for information about how long the server stores the ID, see the reference for your API.

For example, when you include a previously specified PayPal-Request-Id header in a request, PayPal returns the latest status of the previous request that used that same header. Conversely, when you omit the PayPal-Request-Id header from a request, PayPal duplicates the request.

Note: When you send two simultaneous API requests with same PayPal-Request-Id header, PayPal processes the first request and might fail the second request.

Example

A capture authorized payment request that includes a PayPal-Request-Id header times out but the server captures the payment.

You retry the original request with the same PayPal-Request-Id header:

curl -v -X POST https://api.sandbox.paypal.com/v2/payments/authorizations/0VF52814937998046/capture \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440010" \
  -d '{
  "amount": {
    "value": "10.99",
    "currency_code": "USD"
  },
  "invoice_id": "INVOICE-123",
  "final_capture": true
}'

If this request succeeds, PayPal returns the latest status of the request, which is the HTTP 201 Created status code and a JSON response body that shows captured payment details. The server does not capture the payment again because the capture succeeded in the first call.

{
  "id": "2GG279541U471931P",
  "status": "COMPLETED",
  "links": [
    {
      "rel": "self",
      "method": "GET",
      "href": "https://api.paypal.com/v2/payments/captures/2GG279541U471931P"
    },
    {
      "rel": "refund",
      "method": "POST",
      "href": "https://api.paypal.com/v2/payments/captures/2GG279541U471931P/refund"
    },
    {
      "rel": "up",
      "method": "GET",
      "href": "https://api.paypal.com/v2/payments/authorizations/0VF52814937998046"
    }
  ]
}

Usage notes

  • The PayPal-Request-Id header value must be unique for both each request and an API call type. For example, authorize payment and capture authorized payment.
  • PayPal recommends that you use the UUID standard for the PayPal-Request-Id header value because it meets the 38 single-byte character limit.
  • PayPal provides the status of a request at the current time and not the status of the original request.

Support, docs, and resources