REST API authentication and headers

To make a REST API call, you must include request headers including the Authorization header with an OAuth 2.0 access token.

To get an access token, you must create a PayPal app. When you create an app, PayPal generates a set of OAuth client_id and secret keys for your app for both the sandbox and live environments. Then, to get an access token, you pass the client_id:secret credentials in the Authorization header in a get access token request. The authorization server issues an access token in exchange for your client ID and secret credentials. You use the access token for authentication when you make REST API requests.

For more information, see make your first call. If you are a non-US developer, see International Developer Questions. You can use your sandbox access token to try any of the code in the REST API reference.

Request header Description
Authorization To request an access token, send your client_id and secret values as the HTTP basic authentication credentials.
If you use cURL, specify -u "client_id:secret".
When you call APIs, send the value as the OAuth 2.0 access token with the authentication type set as Bearer. For example: Authorization: Bearer Access-Token.
Required.
Accept Set to application/json. Required.
PayPal-Request-Id Contains a unique ID that you generate that can be used for enforcing idempotency.
Note: Omitting this header increases the risk of duplicate transactions.
PayPal-Partner-Attribution-Id Use this header if you are a PayPal partner. Specify a unique BN Code to receive revenue attribution. To learn more or to request a BN Code, contact your Partner Manager or visit the PayPal Partner Portal.
PayPal-Client-Metadata-Id PayPal uses this client metadata ID to verify that the payment is originating from a valid, user-consented device+application. This helps reduce fraud and decrease declines. Transactions that do not include a client metadata ID are not eligible for PayPal Seller Protection. To initiate a pre-consented payment from a mobile device, see future payments.

OAuth request / response

Use the OAuth request to get an access token for use with your payments calls.

For authentication and authorization related to Identity, learn how to obtain a user’s consent.

Requests

Include the client_id:secret as your basic auth credentials.

Tip: Learn more about how PayPal uses OAuth 2.0.

Property Type Description
grant_type string Token grant type. Must be set to client_credentials. Required.
content-type string Set to application/x-www-form-urlencoded for access token requests. By default, cURL sets this value so it is not shown in the request sample. However, you might need to explicitly set this value for non-cURL implementations.

Request sample

curl https://api.sandbox.paypal.com/v1/oauth2/token \
  -H "Accept: application/json" \
  -H "Accept-Language: en_US" \
  -u "client_id:secret" \
  -d "grant_type=client_credentials"

Response

Property Type Description
scope string Scopes expressed in the form of resource URL endpoints. The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings.
Value assigned by PayPal.
access_token string The access token issued by PayPal. After the access token expires (see expires_in), you must request a new access token.
Value assigned by PayPal.
token_type string The type of the token issued as described in OAuth2.0 RFC6749, Section 7.1. Value is case insensitive.
Value assigned by PayPal.
expires_in integer The lifetime of the access token, in seconds.
Value assigned by PayPal.

Response sample

{
  "scope": "https://api.paypal.com/v1/payments/.* https://api.paypal.com/v1/vault/credit-card https://api.paypal.com/v1/vault/credit-card/.*",
  "access_token": "EEwJ6tF9x5WCIZDYzyZGaz6Khbw7raYRIBV_WxVvgmsG",
  "token_type": "Bearer",
  "app_id": "APP-6XR95014BA15863X",
  "expires_in": 28800
}

You get a user’s consent to make Identity API calls on their behalf by redirecting them to the authorization endpoint. For more information, see the Identity API.

Authorization endpoint:

  • Live

    https://www.paypal.com/signin/authorize
    
  • Sandbox

    https://www.sandbox.paypal.com/signin/authorize
    

Note: The live environment supports the optional ISO-3166-1 country code:

https://www.paypal.com/country-code/signin/authorize

If you include this two-letter code and translated content is available for the app and and the language is left-to-right, a localized page appears.

Use the following URL with browser redirect (HTTP 302) to invoke the login flow from the application to Log In with PayPal:

Property Type Description
client_id string Unique client ID obtained through the application registration process. Required.
response_type string A valid value is:
  • code. Requests that an authorization code be sent to the application return URL. Recommended, as access tokens are not visible in the user-agent.
  • token. Returns a token. Typically used mostly by public clients, such as JavaScript or mobile applications.
  • id_token. For session assertion associated with the user’s authentication. For example, used in remote procedure calls for explicit session management such as logout.
scope string URL-encoded, space-separated list of requested scope URIs. For example (URL-encoded): “profile+email+address”. For a list of possible values, see Log In with PayPal User Attributes.
redirect_uri string Application return URL where the authorization code is sent. The specified redirect_uri must match the return URL registered for your app on the My Apps & Credentials page of the PayPal Developer site. All parts of the specified redirect_uri, including protocol, host, port, context path, and query parameter names and values must match with the exception of the state parameter. You can use the state parameter to pass information that was not known at the time the return URL for your app was registered. You must URL-encode and Base64-encoded the state parameter value.
nonce string An opaque, random ID to mitigate replay attacks. A simple function is: (timestamp + Base64 encoding (random\[16\])).
state string Any state parameter that the application might require to know the request context.

The Log In with PayPal authorization endpoint validates the authorization/authentication request and directs the user to log in. After successful login, a consent message is displayed to the user. A user consent grants the requesting application access to the user’s PayPal attributes, as indicated by the scope specified in the request.

Return to application

After the user grants consent, PayPal redirects (HTTP 302) the user to the return URL with an authorization code appended to the URL. Use the authorization code to get a refresh token and initial access token.

https://www.sandbox.paypal.com/signin/authorize
  ?client_id=client_id&response_type=code&scope=profile+email+address+phone+https%3A%2F%2Furi.paypal.com%2Fservices%2Fpaypalattributes&redirect_uri=http://example.com/myapp/return.php
http://example.com/myapp/return.php?scope=profile+email+address+phone+https%3A%2F%2Furi.paypal.com%2Fservices%2Fpaypalattributes&code=Authorization-Code