Get Started

The PayPal APIs are HTTP-based RESTful APIs that use OAuth 2.0 for authorization. API request and response bodies are formatted in JSON.

Important: You cannot run the sample requests in this guide as-is. Replace call-specific parameters such as tokens and IDs with your own values.

If you are a non-US developer, see International Developer Questions.

For definitions of common REST API terms, see the Glossary.

Authentication and authorization

The PayPal REST API uses 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 an app, PayPal generates a set of OAuth client ID and secret credentials for your app for both the sandbox and live environments. You pass these credentials in the Authorization header in a get access token request.

In exchange for these credentials, the PayPal authorization server issues access tokens called bearer tokens that you use for authorization when you make REST API requests. A bearer token enables you to complete actions on behalf of, and with the approval of, the resource owner.

The Access-Token field in the get access token response contains a bearer token, indicated by the token_type of Bearer:

{
  "scope": "scope",
  "nonce": "nonce",
  "Access-Token": "Access-Token",
  "token_type": "Bearer",
  "app_id": "APP-80W284485P519543T",
  "expires_in": 32398
}

Include this bearer token in API requests in the Authorization header with the Bearer authentication scheme.

Note: To get a bearer token, contact your PayPal account manager.

This sample request uses a bearer token to list invoices for a merchant:

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 in the get access token response indicates the lifetime, in seconds, of the access token. For example, an expiry value of 3600 indicates that the access token expires in one hour from the time 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. The value is expressed in seconds.

  • Handle the HTTP 401 Unauthorized status code. The API endpoint issues this status code when it detects an expired token.

Before you create another token, re-use the access token until it expires. See the rate limiting guidelines.

API requests

This sample request cancels a billing agreement:

curl -v -X POST https://api.sandbox.paypal.com/v1/payments/billing-agreements/I-1TJ3GAGG82Y9/cancel \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "note": "Canceling the profile."
}'

The following table describes the components of this and all API requests.

To construct a REST API request, combine these components:

Component Description

The HTTP method

GETRequests data from a resource.
POSTSubmits data to a resource to process.
PUTUpdates a resource.
PATCHPartially updates a resource.
DELETEDeletes a resource.

The URL to the API service

Sandboxhttps://api.sandbox.paypal.com
Livehttps://api.paypal.com

The URI to the resource

The resource to query, submit data to, update, or delete. For example, v1/invoicing/invoices.

Query parameters for filtering and pagination

Optional. Controls which data appears in the response. Use to filter the items, limit the size of the data, and sort the data in the response.

HTTP request headers

Includes the Authorization header with the access token.

A JSON request body, if required

Required for most GET, POST, PUT, and PATCH calls.

Query parameters

You can specify one or more optional query parameters on the request URI to filter and sort the items that are returned in an API response and limit the size of the data returned in that response.

Operations that take query parameters

You can use query parameters to filter, page, and sort the items that are returned in the responses to these requests:

API Requests
Billing Agreements List agreement transactions
Billing Plans List plans
Customer Disputes List disputes
Identity Get user information
Invoicing Send invoice
Update invoice
List merchant invoices
Generate QR code
List templates
Merchant Onboarding Show account tracking details
Show merchant status
Payments List payments
Payouts Create payouts
Show batch payout details
Vault List vaulted credit cards
Webhooks List all webhooks
List event notifications

Query parameters for pagination

To page and sort the data that is returned in some API responses, use these query parameters:

Parameter Type Description
page integer The zero-relative start index of the entire list of items that are returned in the response. So, the combination of page=0 and page_size=20 returns the first 20 items. The combination of page=20 and page_size=20 returns the next 20 items.
page_size integer The number of items to return in the response.
total_count_required boolean Indicates whether to show the total count in the response.
sort_by string Sorts the payments in the response by a specified value, such as the create time.
sort_order string Sorts the items in the response in ascending or descending order.

For example, the Invoicing API returns details for four invoices beginning with the third invoice and includes the total count of invoices in the response:

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"

HTTP request headers

The following table describes the commonly used HTTP request headers:

Header Description
Accept

The response format. Required for operations with a response body. The syntax is:

Accept: application/format

Where format is json.

Authorization

Required to get an access token or make API calls.

To get an access token, set this header to your client_id and secret credential values.

Note: If you use cURL, specify -u "client_id:secret".

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme:

Authorization: Bearer Access-Token
Content-Type

The request format. Required for operations with a request body. The syntax is:

Content-Type: application/format

Where format is json.

PayPal-Client-Metadata-Id

Optional. Verifies that the payment originates from a valid, user-consented device and application. Reduces fraud and decreases 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.

PayPal-Partner-Attribution-Id

Optional. Indicates that you are a PayPal partner. To receive revenue attribution, specify a unique build notation (BN) code. BN codes provide tracking on all transactions that originate or are associated with a particular partner. To learn more or to request a BN code, contact your partner manager or visit the PayPal Partner Portal.

Note: The Payouts API does not support BN codes.
PayPal-Request-Id

Optional. Contains a unique user-generated ID that you can use to enforce idempotency.

Note: If you omit this header, the risk of duplicate transactions increases.

API responses

Hypermedia as the Engine of Application State (HATEOAS) is a constraint of the REST application architecture that distinguishes it from other network application architectures.

Each PayPal API call response includes an array of contextual HATEOAS links, if available. Use these links to request more information about and construct an API flow that is relative to a specific request.

This excerpt from a sample response shows an array of HATEOAS links:

{  
  "links": [{
    "href": "https://api.paypal.com/v1/payments/sale/36C38912MN9658832",
    "rel": "self",
    "method": "GET"
  }, {
    "href": "https://api.paypal.com/v1/payments/sale/36C38912MN9658832/refund",
    "rel": "refund",
    "method": "POST"
  }, {
    "href": "https://api.paypal.com/v1/payments/payment/PAY-5YK922393D847794YKER7MUI",
    "rel": "parent_payment",
    "method": "GET"
  }]
}

You can use the links in this example, as follows:

  • Use the self link to get more information about the request. Combine the method and the target URL to make the call:
    GET https://api.paypal.com/v1/payments/sale/36C38912MN9658832
    
  • Use the refund link to request a refund:
    POST https://api.paypal.com/v1/payments/sale/36C38912MN9658832/refund
    
  • Use the parent_payment link to get information about the parent payment:
    GET https://api.paypal.com/v1/payments/payment/PAY-5YK922393D847794YKER7MUI
    

The elements in the link object are:

Element Required Description
href Required The target URL.
rel Required The link relationship type.
method Optional The HTTP method. Default is GET.

The href element

The href element contains the complete target URL, or link, to use in combination with the HTTP method to make the related call. href is the key HATEOAS component that links a completed call with a subsequent call.

The rel element

The rel element contains the link relationship type, or how the href link relates to the previous call.

For a complete list of the link relationship types, see Link Relationship Types.

The method element

Optional. The method element contains an HTTP method. If present, use this method to make a request to the target URL. If absent, the default method is GET.

The HTTP methods are:

Method Description
DELETE Deletes a resource.
GET Shows details for a resource or lists resources.
PATCH Partially updates a resource.
POST Creates or manages a resource.
PUT Updates a resource.
REDIRECT Not an HTTP method but specifies that the target URL is a redirect URL to which to redirect payers to approve a PayPal account payment.

HTTP status codes

PayPal returns a success or error HTTP status code for each request.

Successful requests

In the responses, PayPal returns these HTTP status codes for successful requests:

Status code Description
200 OK The request succeeded.
201 Created A POST method successfully created a resource. If the resource was already created by a previous execution of the same method, for example, the server returns the HTTP 200 OK status code.
202 Accepted The server accepted the request and will execute it later.
204 No Content The server successfully executed the method but returns no response body.

Failed requests

In the responses, PayPal returns an error HTTP status code for all errors.

For all errors except Identity errors, PayPal returns an error response body that includes additional error details in this format:

{  
    "name": "ERROR_NAME",
    "message": "ERROR_DESCRIPTION",
    "information_link": "ERROR_DOCUMENTATION_LINK",
    "details": "ERROR_DETAILS"
}

The response body for Identity errors includes additional error details in this format:

{  
    "error": "ERROR_NAME",
    "error_description": "ERROR_DESCRIPTION"
}

PayPal returns these HTTP status codes and error messages for failed requests:

HTTP status code Error message Error Code Cause
400 Bad Request Request is not well-formed, syntactically incorrect, or violates schema. INVALID_REQUEST See Validation errors. The request could not be understood by the server. This status code indicates one of the following conditions:
  • The data as part of the payload cannot be converted to the underlying data type.
  • The data is not in the expected data format.
  • Required field is not available.
  • Simple data validation type of error.
401 Unauthorized Authentication failed due to invalid authentication credentials. AUTHENTICATION_FAILURE See Authentication errors. The request requires authentication and none was provided. Note the difference between this and 403 Forbidden.
403 Forbidden Authorization failed due to insufficient permissions. NOT_AUTHORIZED The client is not authorized to access this resource although it might have valid credentials. For example, the client does not have the correct OAuth 2 scope. Additionally, a business-level authorization error might have occurred. For example, the account holder does not have sufficient funds.
404 Not Found The specified resource does not exist. RESOURCE_NOT_FOUND The server did not found anything that matches the request URI. Either the URI is incorrect or the resource is not available. For example, no data exists in the database at that key.
405 Method Not Allowed The server does not implement the requested HTTP method. METHOD_NOT_SUPPORTED The service does not support the requested HTTP method. For example, PATCH.
406 Not Acceptable The server does not implement the media type that would be acceptable to the client. MEDIA_TYPE_NOT_ACCEPTABLE The server cannot return the payload of the response by using the media type requested by the client. For example, if the client sends an Accept: application/xml header and the API can generate only application/json, the server returns the 406 status code.
415 Unsupported Media Type The server does not support the request payload’s media type. UNSUPPORTED_MEDIA_TYPE The media type of the payload cannot be processed. For example, if the client sends a Content-Type: application/xml header but the API can only accept application/json, the server returns the 415 status code.
422 Unprocessable Entity The requested action could not be performed, is semantically incorrect, or failed business validation. UNPROCCESSABLE_ENTITY The requested action cannot be completed and might require interaction with APIs or processes outside of the current request. This response is distinct from a 500 response because no systemic problems limit the API from completing the request. For example, APIs use this code for any business validation errors, including errors that are not usually of the 400 type.
429 Unprocessable Entity Too many requests. Blocked due to rate limiting. RATE_LIMIT_REACHED The rate limit for the user, application, or token exceeded a predefined value. See RFC 6585.
500 Internal Server Error An internal server error has occurred. INTERNAL_SERVER_ERROR A system or application error occurred. Although the client appears to provide a correct request, something unexpected occurred on the server. A 500 response indicates a server-side software defect or site outage. The 500 status code is not used for client validation or logic error handling.
503 Service Unavailable Service Unavailable. SERVICE_UNAVAILABLE The server cannot handle the request for a service due to temporary maintenance.

Validation errors

For validation errors, PayPal returns the HTTP 400 Bad Request status code.

To prevent validation errors, ensure that parameters are of the right type and conform to these constraints:

Parameter type Description
Character Names, addresses, phone numbers, and so on have maximum character limits.
Numeric Credit cards, amounts, card verification value (CVV), and so on must use non-negative numeric values and have required formats. For example, a CVV must be three or four numbers while a credit card number must contain only numbers.
Required Must be included in the request. For example, when you provide credit card information, you must include a postal code for most countries.
Monetary Must use the right currency.

For information about parameter types and constraints, see the REST API reference.

Authentication errors

For authentication errors, PayPal returns the HTTP 401 Unauthorized status code. See authentication and authorization.

Access token-related issues often cause authentication errors.

Ensure that the access token is valid and present and not expired.

Make your first call

To make REST API calls, create a PayPal REST app and get an access token:

1. Create a PayPal app.
When you create an app, PayPal generates a set of OAuth credentials.
2. Get an access token.
Pass the OAuth credentials in a get access token call.
In response, the PayPal authorization server issues an access token.
3. Make REST API calls.
Use the access token for authentication when you make REST API calls.

Create a PayPal app

On the My Apps & Credentials page, click Log into Dashboard.

In the REST API apps section, click Create App.

PayPal generates a set of OAuth 2.0 client_id and secret credentials for your app for both the sandbox and live environments.

Get an access token

The get access token endpoint is /v1/oauth2/token.

To get an access token, you pass your OAuth credentials in a get access token call. To make this call, you can use either cURL on the command line or the Postman app.

In response, the PayPal authorization server issues an access token.

Re-use the access token until it expires. See our rate limiting guidelines. When it expires, you can get a new token.

cURL example

  1. Download cURL for your environment.

  2. From the command line, run this command:

    curl -v 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"

    Where:

    /v1/oauth2/token The get access token endpoint.
    client_id Your client ID.
    secret Your secret.
    grant_type The grant type. Set to client_credentials.
  3. View the sample response.

Tips:

  • If you use Windows, use a Bash shell to make cURL calls.
  • If you use a command-line tool other than cURL, set content-type to application/x-www-form-urlencoded.

Postman example

  1. Download Postman for your environment, and open Postman.

  2. On the Authorization tab, select or enter this information:

    Method POST
    Endpoint

    https://api.sandbox.paypal.com/v1/oauth2/token

    Username Your client ID.
    Password Your secret.
  3. On the Body tab, select or enter this information:

    Content type x-www-form-urlencoded
    key grant_type
    value client_credentials
  4. Click Send.

  5. View the sample response.

Sample response

{
  "scope": "https://uri.paypal.com/services/subscriptions https://api.paypal.com/v1/payments/.* https://api.paypal.com/v1/vault/credit-card https://uri.paypal.com/services/applications/webhooks openid https://uri.paypal.com/payments/payouts https://api.paypal.com/v1/vault/credit-card/.*",
  "nonce": "2017-06-08T18:30:28ZCl54Q_OlDqP6-4D03sDT8wRiHjKrYlb5EH7Di0gRrds",
  "Access-Token": "Access-Token",
  "token_type": "Bearer",
  "app_id": "APP-80W284485P519543T",
  "expires_in": 32398
}

Where:

Access-Token Your access token.
expires_in The number of seconds after which the token expires. Request another token when the current one expires.

Make REST API calls

With a valid access token, you can make REST API calls.

This sample call creates a PayPal account payment and uses only the required input parameters. The access token in the call is an OAuth bearer token.

Note: Payments API calls are always made by an actor, such as email, on behalf of a subject, or the payer. The actor specifies a bearer token in the Authorization: Bearer request header. A bearer token is an access token that is issued to the actor by an authorization server with the approval of the resource owner, or payer. In this case, the actor uses the bearer token to make a payments request on behalf of the subject.

curl -v https://api.sandbox.paypal.com/v1/payments/payment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -d '{
  "intent": "sale",
  "redirect_urls": {
    "return_url": "https://example.com/your_redirect_url.html",
    "cancel_url": "https://example.com/your_cancel_url.html"
  },
  "payer": {
    "payment_method": "paypal"
  },
  "transactions": [{
    "amount": {
      "total": "7.47",
      "currency": "USD"
    }
  }]
}'

A successful call returns a JSON-formatted response body with payment details.

Additional information

Authentication and authorization
HTTP request headers
HATEOAS links
Internet date and time format
Support
API reference
SDKs