REST API overview

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

The PayPal API uses HTTP methods and a RESTful endpoint structure. The API authorization framework is OAuth 2.0. You format requests in JSON and the APIs return JSON-formatted responses.

• API operations
• Authentication and headers
• Filtering and pagination
• HATEOAS links

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.

API operations

Use the PayPal REST APIs in these environments:

Note: For the PayPal NVP and SOAP API endpoints, see NVP/SOAP API endpoints.

To construct a REST call, combine:

• The HTTP method
• The full URI to the resource
• HTTP headers, if required
• The JSON-formatted payload, if required

For example, this request creates a payment:

curl -v https://api.sandbox.paypal.com/v1/payments/payment \
-H "Content-Type:application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "intent": "sale",
  "payer":
  {
    "payment_method": "credit_card",
    "funding_instruments": [
    {
      "credit_card":
      {
        "number": "4012888888881881",
        "type": "visa",
        "expire_month": 11,
        "expire_year": 2018,
        "cvv2": "874",
        "first_name": "Betsy",
        "last_name": "Buyer",
        "billing_address":
        {
          "line1": "111 First Street",
          "city": "Saratoga",
          "state": "CA",
          "postal_code": "95070",
          "country_code": "US"
        }
      }
    }]
  },
  "transactions": [
  {
    "amount":
    {
      "total": "7.47",
      "currency": "USD",
      "details":
      {
        "subtotal": "7.41",
        "tax": "0.03",
        "shipping": "0.03"
      }
    },
    "description": "This is the payment transaction description."
  }]
}'

Note: You can use cURL commands on the command line to try code. If needed, download cURL software. Include your own access token and payment-specific IDs for calls.

Filtering and pagination

You can use query parameters to filter and page the responses to these GET requests:

• List payments
• List plans
• List transactions for billing agreement
• List stored credit cards
• List merchant invoices
• List templates
• List event notifications

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"

HATEOAS links

Each API call response includes an array of Hypermedia as the Engine of Application State (HATEOAS) links. HATEOAS enables you to interact and construct an API flow solely through the provided hyper-links. You no longer need to hard code logic into your client to use our API. We provide HATEOAS links for each call and for transactions within a call, if available.

This code shows a sample of HATEOAS links:

{
  "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"
  }]
}

Learn more about how the REST Payment API uses HATEOAS.