Developer process

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

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

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:

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.

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.