Orders API Integration Guide for Express Checkout

Overview

Use the Orders API to easily and securely accept online and mobile PayPal payments. This guide shows you how to create, view, authorize payments, and capture authorized payments for orders.

Integration steps

To integrate payment processing through the Orders API:


1.	Required	Set up your development environment.
2.	Required	Add a PayPal button.
3.	Required	Create an order.
4.	Required	Get payment approval.
5.	Optional	Authorize and capture payment for an order.
6.	Optional	View order details.
7.	Optional	Refund an order.

Set up your development environment

Before you can integrate Orders, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.

Then, return to this page to integrate Orders.

Download these Postman Collections to quickly start running the API:

PayPal Express Checkout API Collection (Capture) — Capture payments immediately.
PayPal Express Checkout API Collection (Auth & Capture) — Authorize payments first, then capture later.

Add PayPal button

To create the best checkout process for your customers and increase your conversion rates, consider where you will place the PayPal Checkout button on your site. To learn more, see Choose the optimal button location.

Add the script to your client

For Express Checkout integrations, PayPal provides the JavaScript checkout.js script. Add the checkout.js script to your client on the page where you want to render the PayPal button:

Note: To ensure maximum compatibility with Express Checkout, load the script from https://www.paypalobjects.com/api/checkout.js. Do not download a local copy to your server and load the script from there.

<!DOCTYPE html>

<head>
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <script src="https://www.paypalobjects.com/api/checkout.js"></script>
</head>

<body>
  <div id="paypal-button"></div>

  <script>
    paypal.Button.render({
      env: 'production', // Or 'sandbox',

      commit: true, // Show a 'Pay Now' button

      style: {
        color: 'gold',
        size: 'small'
      },

      payment: function(data, actions) {
        /*
         * Set up the payment here
         */
      },

      onAuthorize: function(data, actions) {
        /*
         * Execute the payment here
         */
      },

      onCancel: function(data, actions) {
        /*
         * Buyer cancelled the payment
         */
      },

      onError: function(err) {
        /*
         * An error occurred during the transaction
         */
      }
    }, '#paypal-button');
  </script>
</body>

Checkout script options

In your PayPal checkout script, you'll configure the look and feel of your checkout button, initiate a payment, and then define what happens when a buyer authorizes or cancels a payment. Finally, you'll determine what happens if an error occurs.


Option	Description
`#paypal-button`	Selector that refers to the container element into which the PayPal button is rendered.
`style`	Option that allows you to customize the button's appearance.
`payment()`	Function called by `checkout.js` when a buyer clicks the PayPal button. This is where you set up and return a payment to initiate the checkout process.
`onAuthorize()`	Function called by `checkout.js` after the buyer logs in and authorizes the payment on paypal.com. This is where you optionally show a confirmation page, and then execute the payment.
`onCancel()`	Function called by `checkout.js` if the buyer cancels the payment. By default, the buyer is returned to the original page, but you're free to use this function to take them to a different page.
`onError()`	Function called by `checkout.js` when an error occurs. You can enable the buyer to re-try or show an error message.

Create order

To create an order:

POST /v1/checkout/orders

Include Authorization, Accept, PayPal-Request-Id and Content-Type headers in your request. For more information about these headers, see REST API authentication and headers.

These fields are commonly used to define an order request:

Parameter	Description
`intent`	Set to one of the following: `SALE`. If you intend to capture payment immediately after the customer approves the payment. `AUTHORIZE`. An authorization places a hold on the funds and is valid for 29 days. After a successful authorization, PayPal recommends that you capture the funds within the three-day honor period. Success of the capture is subject to risk and availability of funds on the authorized funding instrument. Within the 29-day authorization period, you can issue multiple re-authorizations after the honor period expires. A re-authorization generates a new Authorization ID and restarts the honor period, and any subsequent capture should be performed on the new Authorization ID. If you do a re-authorization on the 27th day of the authorization, you get only two days of honor period.
`application_context`	As a merchant, you can use this object to customize the PayPal payment flow experience.
`redirect_urls`	Specify the return and cancel URLs: `return_url`. The URL on your website to which to redirect a customer when he or she approves a payment. `cancel_url`. The URL on your website to which to redirect a customer when he or she cancels a payment.
`payment_method`	Set to `paypal` to choose the PayPal payment method.
`purchase_units`	An array with details for the customer, merchant, partner, and order. Specify this information optionally: `reference_id`. The purchase unit within the context of the order. `description`. The purchase unit description. `invoice_number` An external invoice number for this order. This value is returned in transaction and settlement reports.

Sample API request

Example create order request:

POST https://api.sandbox.paypal.com/v1/checkout/orders
  -H "PayPal-Request-Id: b992fcd6-41b6-43b5-b99a-be9acaf85727"
  -H "Authorization: Bearer Access-Token"
  -H "Accept: application/json"
  -H "Content-Type: application/json"
  -d '{
  "intent":"SALE",
  "application_context":{
    "locale":"en-US",
    "brand_name":"My Shop",
    "landing_page":"login",
    "shipping_preference":"get_from_file",
    "user_action":"commit"
  },
  "purchase_units": [{
    "reference_id": "pu1_forward fashions",
    "description": "pu1_description",
    "amount": {
      "currency": "USD",
      "total": "71.50"
      "details": {
        "subtotal": "65.00",
        "shipping": "0.00",
        "tax": "6.50"
      },
    },
    "payee": {
      "email": "seller@example.com"
    },
    "items":[
    {
      "currency":"USD",
      "name":"Denim Woven Shirt",
      "price":"20.00",
      "tax":"2.00"
      "quantity":"1",
      "sku":"SKU1",
    },
    {
      "currency":"USD",
      "name":"Casual Boots",
      "price":"45.00",
      "tax":"4.50"
      "quantity":"1",
      "sku":"SKU2"
    }
    ],
    "shipping_address": {
      "recipient_name": "John Doe",
      "line1": "2211 N First Street",
      "line2": "Building 17",
      "city": "San Jose",
      "country_code": "US",
      "postal_code": "95131",
      "state": "CA",
      "phone": "(123) 456-7890"
    },
    "shipping_method": "United Postal Service",
    "invoice_number": "INV5511231",
    "payment_descriptor": "My Shop"
  }],
  "redirect_urls": {
    "return_url": "https://example.com/return",
    "cancel_url": "https://example.com/cancel"
  },
}'

Sample API response

The create order call to /checkout/orders/ creates an order with status as created. Save the associated order ID to pass to subsequent calls.
A successful create order request returns an HTTP 2<nn> status code. Any other status value indicates an error. In this case, correct the problem and resubmit the order.

Example response to the preceding order request:

Headers:
201 Created
PayPal-Debug-Id: e6692015bc1c0
Body:
{
  "id": "875532314N",
  "gross_total_amount":
  {
    "value": "71.50",
    "currency": "USD"
  },
  ..."links": [
  {
    "href": "https://api.sandbox.paypal.com/v1/checkout/orders/875532314N",
    "rel": "self",
    "method": "GET"
  },
  {
    "href": "https://www.sandbox.paypal.com/webapps/hermes?token=875532314N",
    "rel": "approval_url",
    "method": "GET"
  }, ],
  "status": "CREATED"
}

The links array contains HATEOAS links that enable you to complete other actions for the order:

Show order details:

GET https://api.sandbox.paypal.com/v1/checkout/orders/875532314N

Get payment approval

When an order is created, the customer must approve the payment before it can be either captured immediately or authorized.

The payment method you created on the client makes a call to your server. On completion of the call the Express Checkout flow is launched in a lightbox on your page and gets the customer's approval for payment.

Authorize and capture payment for an order

Note: To authorize and then capture the order, call create order with intent=AUTHORIZE.

When the customer approves the payment, the checkout.js script calls your onAuthorize call back.

Note: You can show payment details on a confirmation page either before or after you execute the payment.

Your client makes a call to your server in the onAuthorize call back.

The required data.OrderID and data.payerID parameters are passed to your server to execute the payment.
Your server sends a payment authorization request to the Orders API to place a hold on funds (Authorization).

POST /v1/checkout/orders order_id/authorize

Include Authorization, Accept, PayPal-Request-Id and Content-Type headers in your request. For more information about these headers, see REST API authentication and headers.

In the URL, pass the parameter order_id. The request body is empty and the amount authorized is the gross_total_amount as seen in the API response to Create Order.

API request

This example request authorizes payment for an order:

curl -v -X POST https://api.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/authorize \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -H "PayPal-Request-Id: 7b92603e-77ed-4896-8e78-5dea2050476a"

API response

Example response:

Headers:
201 Created
Body:
{
  "id": "5O190127TN364715T",
  "status": "COMPLETED",
  "payer": {
    "name": {
      "given_name": "John",
      "surname": "Doe"
    },
    "email_address": "customer@example.com",
    "payer_id": "QYR5Z8XDVJNXQ"
  },
  "purchase_units": [{
    "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
    "shipping": {
      "address": {
        "address_line_1": "2211 N First Street",
        "address_line_2": "Building 17",
        "admin_area_2": "San Jose",
        "admin_area_1": "CA",
        "postal_code": "95131",
        "country_code": "US"
      }
    },
    "payments": {
      "authorizations": [{
        "id": "0AW2184448108334S",
        "status": "CREATED",
        "amount": {
          "currency_code": "USD",
          "value": "100.00"
        },
        "seller_protection": {
          "status": "ELIGIBLE",
          "dispute_categories": [
            "ITEM_NOT_RECEIVED",
            "UNAUTHORIZED_TRANSACTION"
          ]
        },
        "expiration_time": "2018-05-01T21:20:49Z",
        "create_time": "2018-04-01T21:20:49Z",
        "update_time": "2018-04-01T21:20:49Z",
        "links": [{
            "href": "https://api.paypal.com/v2/payments/authorizations/0AW2184448108334S",
            "rel": "self",
            "method": "GET"
          },
          {
            "href": "https://api.paypal.com/v2/payments/authorizations/0AW2184448108334S/capture",
            "rel": "capture",
            "method": "POST"
          },
          {
            "href": "https://api.paypal.com/v2/payments/authorizations/0AW2184448108334S/void",
            "rel": "void",
            "method": "POST"
          },
          {
            "href": "https://api.paypal.com/v2/payments/authorizations/0AW2184448108334S/reauthorize",
            "rel": "reauthorize",
            "method": "POST"
          }
        ]
      }]
    }
  }],
  "links": [{
    "href": "https://api.paypal.com/v2/checkout/orders/5O190127TN364715T",
    "rel": "self",
    "method": "GET"
  }]
}

To subsequently capture the funds on the order, follow the rel:capture HATEOAS link:

POST https://api.sandbox.paypal.com/v1/payments/authorization/0JF38800GW/capture

Authorization and capture time periods

An authorization places a hold on the funds and is valid for 29 days. After a successful authorization, PayPal recommends that you capture the funds within the three-day honor period. Success of the capture is subject to risk and availability of funds on the authorized funding instrument. Within the 29-day authorization period, you can issue multiple re-authorizations after the honor period expires. A re-authorization generates a new Authorization ID and restarts the honor period, and any subsequent capture should be performed on the new Authorization ID. If you do a re-authorization on the 27th day of the authorization, you get only two days of honor period.

Within a 29-day authorization period, you can issue multiple reauthorizations after the initial three-day honor period expires.

Day	Action	Authorization period	Honor period
1	Authorization-1	Begins 29-day authorization period	Days 1 through 3
4	Reauthorization-1 on Authorization-1	Within 29-day authorization period	Days 4 through 7
8	Reauthorization-2 on Authorization-1	Within 29-day authorization period	Days 8 through 11

For any payment type, you can capture less than or the full original authorized amount. You can also capture up to 115% of or $75 USD more than the original authorized amount, whichever is less.

You can also complete partial captures during a single authorization period. For PayPal payment authorizations, you must enable this feature on your PayPal account.

Note:
Customers and merchants cannot close accounts that have authorized but not yet captured payments.
You can also authorize payments for orders, which confirms the availability of funds but does not place the funds on hold.

View order details

For a transaction, the API response also contains HATEOAS links to show Capture status details and to refund the captured payment.

To view details about the order follow the rel:self

GET https://api.sandbox.paypal.com/v1/payments/capture/29N36144XH0198422

To refund the payment:

POST https://api.sandbox.paypal.com/v1/payments/capture/29N36144XH0198422/refund

Refund payment

To request payment refunds for an order, pass the capture ID in the URI:

POST /v1/payments/capture/capture_id/refund

The capture_id is within the refund link from the capture payment for an order response.

To refund the amount that was captured, make a call with an empty body. Alternately, in the request body, specify:

amount. Currency and total amount to refund.

Include Authorization, Accept, PayPal-Request-Id, and Content-Type headers in your request. For more information about these headers, see REST API authentication and headers.

Example refund request:

POST https://api.sandbox.paypal.com/v1/payments/capture/29N36144XH0198422/refund
  -H "PayPal-Request-Id: 9c5e3668-cb92-4a40-99b7-c74cb68913f4"
  -H "Authorization: Bearer Access-Token"
  -H "Content-Type: application/json"
  -H "Accept: application/json"
  -d '{
  "amount": {
    "total": "60.00",
    "currency": "USD"
  },
}'

The response includes:

An ID for the refund 2M4379007H634953P.
A set of HATEOAS links to show details for the refund, parent payment, and original payout.

Example refund request response:

{
 "id": "2M4379007H634953P",
 "state": "completed",
 "amount": {
   "total": "0.70",
   "currency": "USD"
 },
 "refund_from_received_amount": {
   "value": "0.67",
   "currency": "USD"
 },
 "refund_from_transaction_fee": {
   "value": "0.03",
   "currency": "USD"
 },
 "total_refunded_amount": {
   "value": "0.70",
   "currency": "USD"
 },
 "capture_id": "29N36144XH0198422",
 "create_time": "2017-12-02T14:21:51.051Z",
 "update_time": "2017-12-02T14:21:51.051Z",
 "links": [
   {
     "href": "https://api.sandbox.paypal.com/v1/payments/refund/2M4379007H634953P",
     "rel": "self",
     "method": "GET"
   },
   {
     "href": "https://api.sandbox.paypal.com/v1/checkout/orders/875532314N",
     "rel": "parent_payment",
     "method": "GET"
   },
   {
     "href": "https://api.sandbox.paypal.com/v1/payments/capture/29N36144XH0198422",
     "rel": "capture",
     "method": "GET"
   }
 ]
}

You are now integrated with PayPal Express Checkout.