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. |
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:
|
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:
|
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:
|
Sample API request
Example create order request:
POST https://api-m.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 ascreated. Save the associated order ID to pass to subsequent calls. - A successful create order request returns an
HTTP2<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-m.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-m.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
onAuthorizecall back.The required
data.OrderIDanddata.payerIDparameters 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-m.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-m.paypal.com/v2/payments/authorizations/0AW2184448108334S",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.paypal.com/v2/payments/authorizations/0AW2184448108334S/capture",
"rel": "capture",
"method": "POST"
},
{
"href": "https://api-m.paypal.com/v2/payments/authorizations/0AW2184448108334S/void",
"rel": "void",
"method": "POST"
},
{
"href": "https://api-m.paypal.com/v2/payments/authorizations/0AW2184448108334S/reauthorize",
"rel": "reauthorize",
"method": "POST"
}
]
}]
}
}],
"links": [{
"href": "https://api-m.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-m.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-m.sandbox.paypal.com/v1/payments/capture/29N36144XH0198422
To refund the payment:
POST https://api-m.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-m.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-m.sandbox.paypal.com/v1/payments/refund/2M4379007H634953P",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.sandbox.paypal.com/v1/checkout/orders/875532314N",
"rel": "parent_payment",
"method": "GET"
},
{
"href": "https://api-m.sandbox.paypal.com/v1/payments/capture/29N36144XH0198422",
"rel": "capture",
"method": "GET"
}
]
}
You are now integrated with PayPal Express Checkout.
