REST API overview

Non-US developers: please read our FAQ.

The PayPal API uses HTTP verbs and a RESTful endpoint structure. OAuth 2.0 is used as the API Authorization framework. Request and response payloads are formatted as JSON.

Note: We use cURL calls in this guide so that you can quickly try code via the command line. You can download cURL software if needed. Be sure to include your own access token and payment-specific IDs for calls.

Important: The sample requests in this guide are examples only and not runnable as-is. You should substitute all call-specific parameters (such as tokens and IDs) with your own values.

Important REST API topics

API operations

The PayPal REST APIs are supported in two environments. Use the Sandbox environment for testing purposes, then move to the live environment for production processing. When testing, generate an access token with your test credentials to make calls to the Sandbox URIs. When you’re set to go live, use the live credentials assigned to your app to generate a new access token to be used with the live URIs.

Note: If you’re looking for the endpoints to PayPal’s non-RESTful APIs, refer to the NVP/SOAP API endpoints.

The following endpoints address our two environments:

  • Sandbox (for testing) : https://api.sandbox.paypal.com
  • Live (production) : https://api.paypal.com

A complete REST operation is formed by combining an HTTP method (or “verb”) with the full URI to the resource you’re addressing. For example, here is the operation to create a new payment:

POST https://api.paypal.com/v1/payments/payment

To create a complete request, combine the operation with the appropriate HTTP headers and any required JSON payload.

Paging and Filtering

In HTTP GET requests, you can use input parameters for paging and filtering. The input parameters currently are available for the /v1/payments/payment resource and the /v1/payments/billing-plans resource. See list plans for the Billing Plans input parameters.

You can combine filters, as shown in the sample below.

Paging for one-time payments

For the /v1/payments/payment resource, the following input parameters can be used.

Filter Description
count Number of items to return. Default is 10 with a maximum value of 20.
start_id Resource ID that indicates the starting resource to return. When results are paged, you can use the next_id response value as the start_id to continue with the next set of results.
start_index Start index of the resources to be returned. Typically used to jump to a specific position in the resource history based on its order. Example for starting at the second item in a list of results: ?start_index=2
start_time Resource creation time as defined in RFC 3339 Section 5.6 that indicates the start of a range of results. Example: start_time=2013-03-06T11:00:00Z
end_time Resource creation time that indicates the end of a range of results.
sort_by Sort based on create_time or update_time.
sort_order Sort based on order of results. Options include asc for ascending order or desc for descending order (default).

Request sample

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/payment?sort_order=asc&sort_by=update_time \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer Access-Token"

Each API call response includes an array of HATEOAS (Hypermedia as the Engine of Application State) links. The beauty of HATEOAS is that it allows you to interact and construct an API flow solely through the hyperlinks we provide you. You no longer need to hardcode logic into your client in order to use our API. We provide HATEOAS links for each call and for transactions within a call, if available. Learn more about how the REST Payment API uses HATEOAS.

Element Description
href URL of the related HATEOAS link you can use for subsequent calls.
rel Link relation that describes how this link relates to the previous call. Examples include self (get details of the current call), parent_payment (get details of the parent payment), or a related call such as execute or refund.
method The HTTP method required for the related call. 
"links": [{
  "href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-2XR800907F429382MKEBWOSA",
  "rel": "self",
  "method": "GET"
}, {
  "href" : "https://api.sandbox.paypal.com/v1/payments/payment/PAY-2XR800907F429382MKEBWOSA/execute",
  "rel" : "update",
  "method" : "POST"
}]
scroll to top