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 and capture orders.

Prerequisites

Before you can use the Orders API, you must:

Integration steps

To integrate payment processing through the Orders API:

1. Required Add a PayPal button.
2. Required Create an order.
3. Required Get payment approval.
4. Required Capture an order.
5. Optional Authorize and Capture an order.
6. Optional View an order.
7. Optional Refund an order.

Add PayPal button

For Express Checkout integrations, PayPal provides the JavaScript checkout.js script. To begin the integration, add the checkout.js script to your client, which renders the PayPal button on your web page.

Add the script to your client

To include the checkout.js script, add this code 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>

Understanding the checkout script

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 allow 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:
  • capture. If you intend to capture payment immediately after the buyer approves the payment.
  • authorize. If you only want to put funds on hold and capture payment later.
Authorizations are guaranteed for up to three days, though you can attempt to capture an authorization for up to 29 days. After the three-day honor period authorization expires, you can reauthorize the payment.
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 buyer when he or she approves a payment.
  • cancel_url. The URL on your website to which to redirect a buyer 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":"CAPTURE",
  "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://www.example.com/return",
    "cancel_url": "https://www.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 2nn 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 buyer's approval for payment.

Capture order

When the buyer 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 capture the payment.

  1. 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 capture the payment.

  2. Your server sends a capture order request to the Orders API and captures the payment.

POST /v1/checkout/orders/order_id/capture

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. Specify the ID returned from the call to create the order.

API request

Example capture order request:

POST https://api.sandbox.paypal.com/v1/checkout/orders/875532314N/capture
-H “PayPal-Request-Id: 9c5e3668-cb92-4a40-99b7-c74cb68913f4”
-H “Authorization: Bearer Access-Token”
-H “Content-Type: application/json”
-H “Accept: application/json”

API response

Example capture order response:

Headers:
201 Created
Body:
{
  "order_id": "875532314N",
  "status": "APPROVED",
  "payer_info": {
    ...
  }
},
"purchase_units": [],
"links": [{
    "href": "https://api.sandbox.paypal.com//v1/checkout/orders/875532314N",
    "rel": "self",
    "method": "GET"
  },
  {
    "href": "https://api.sandbox.paypal.com/v1/payments/capture/875532314N/refund",
    "rel": "refund"
    "method": "POST"
  }
]}

Authorize and Capture order

Note: To authorize first and then capture the order later, it is important that Create order is called with intent=AUTHORIZE.

When the buyer 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.

  1. 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.

  2. 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

Example request for authorizing an order:

POST https://api.sandbox.paypal.com/v1/checkout/orders/875532314N/authorize
-H “PayPal-Request-Id: 9c5e3668-cb92-4a40-99b7-c74cb68913f4”
-H “Authorization: Bearer Access-Token”
-H “Content-Type: application/json”
-H “Accept: application/json“

API response

Example response:

Headers:
201 Created
Body:
{
  "order_id": "875532314N",
  "status": "APPROVED",
  "intent":"AUTHORIZE",
  "payer_info": {
    ...
  }
},
"gross_total_amount": {
    "value": "1.18",
    "currency": "USD"
},
"purchase_units": [
  ...
  ...
  "payment_summary": {
      "authorizations": [
          {
              "id": "0JF38800GW",
              "amount": {
                  "currency": "USD",
                  "details": {
                      "subtotal": "65.00",
                      "shipping": "0.00",
                      "tax": "6.50",
                      "handling_fee": "0.00",
                      "shipping_discount": "0.00",
                      "insurance": "0.00"
                  },
                  "total": "71.50"
              },
              "create_time": "2017-07-26T07:09:38Z",
              "update_time": "2017-07-26T07:09:38Z",
              "links": [
                  {
                      "href": "https://api.sandbox.paypal.com/v1/checkout/orders/875532314N"
                      "rel": "self",
                      "method": "GET"
                  },
                  {
                      "href": "https://api.sandbox.paypal.com/v1/payments/authorization/0JF38800GW/capture",
                      "rel": "capture",
                      "method": "POST"
                  },
                  {
                      "href": "https://api.sandbox.paypal.com/v1/payments/authorization/0JF38800GW/void",
                      "rel": "void",
                      "method": "POST"
                  },
                  {
                      "href": "https://api.sandbox.paypal.com/v1/payments/authorization/0JF38800GW/reauthorize",
                      "rel": "reauthorize",
                      "method": "POST"
                  }
              ]
          }
      ]
  },
],
}

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 includes these time periods:

Period Duration Description
Authorization period

A 29-day period that begins when the buyer authorizes the payment.

Note: A day starts at 12AM PST and ends at 11:59PM PST on the calendar day when the authorization occurs.

The authorization places the buyer's balance on hold to ensure that you can capture the funds.

Honor period

A three-day period from day one to day three of the authorization period.

PayPal honors 100% of authorized funds during this period. You can, however, attempt to capture an authorized payment any time during the entire 29-day authorization period but PayPal cannot guarantee that 100% of the funds are still available.

You can only re-authorize a payment after the honor period concludes.

To ensure that funds are still available, you can re-authorize a payment after the initial three-day honor period. You can re-authorize a payment only once from days four to 29 after the three-day honor period for the original authorization expires. If 30 days have passed from the original authorization, you must create a new authorization instead. A re-authorized payment itself has a new three-day honor period. You can re-authorize a transaction once for up to 115% of the original authorization or $75 USD more, whichever is less.

For any payment type, you can capture less than the 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: Buyers and merchants cannot close accounts that have authorized payments that have not yet been captured.

View an order

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 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.