How to use PayPal REST APIs

Learn how to use the PayPal Orders v2 API and supported use cases.

Know before you code

If you are a first-time user who wants to know where to get your access token, how to use the API suite, and complete Postman setup details, refer to Get started with PayPal REST APIs.

See PayPal's Postman Collection for the latest Orders v2 API payloads.

Note: Set up your server to call the Orders v2 API instead of making calls directly from the browser or the client-side.

Why use this guide?

This guide explains fundamental integration tips for first-time users integrating the Orders v2 API, such as:

How to get started and set up the environment.
Where the Orders v2 API fits into the checkout process.
Where to find the samples and examples that show how to use the Orders v2 API.

How it works

The Orders v2 API connects PayPal payment services with merchant and partner applications such as websites, software applications, and other channels. The API endpoints provide a layer of abstraction from the payments and enable a secure and seamless integration experience.

This documentation includes workflows for detailed use cases such as PayPal Checkout and Expanded Checkout.

The following section explains the 2 basic use cases for the Orders v2 API.

Use case 1: PayPal Checkout

Use the Orders v2 API when a buyer uses PayPal Checkout to start a payment, the merchant wants to capture the payment immediately, and the order intent is CAPTURE.

The PayPal Checkout Process diagram shows the basic checkout process, from when the buyer adds an item to the cart, to making the payment and placing the order.

Process flow

The buyer looks through the items on the merchant's site and adds an item to their cart.
The buyer goes to check out, and selects the PayPal button.
The merchant calls the Create order API endpoint with the product details. If successful, this call returns an order ID, an approval URL, and a return URL.
The merchant redirects the buyer to the approval URL.
The buyer sees a payment page with various payment options, such as credit card or PayPal.
The buyer chooses a payment method and approves the order.
The buyer is redirected to the return URL from the original Create order API call from step 3.
The merchant calls the Capture payment for order endpoint to capture and complete the payment. This completes the order process.

The Orders v2 API includes the following features:

Merchants can update the order at any time before completion.
Merchants can add shipping tracking information to the order.
Merchants can view the order details at any stage.

PayPal Checkout process

Checkout flow

Use case 2: PayPal Checkout with authorize and capture

Use the Orders v2 API when a buyer uses PayPal Checkout to start a payment, and the merchant or partner wants to authorize the buyer's funds before capturing and settling the funds later. This is otherwise similar to the preceding PayPal Checkout use case section. Example use cases include:

Ensure an item is in stock before completing the payment.
Ask the buyer to authorize the transaction, and charge them only after the item is shipped.

An authorization puts a hold on the funds and is valid for 29 days.

For more information, see Authorize a payment and capture funds later.

PayPal Checkout with auth and capture

Checkout with auth and capture

API endpoints

Endpoint	HTTP method	Description
Create order `v2/checkout/orders`	`POST`	The entry point of a transaction. This endpoint accepts item details such as `name`, `desc`, `quantity`, and amount. It also supports advanced options such as adding payment sources and shipping.
Authorize order `v2/checkout/orders/ORDER-ID/authorize`	`POST`	Authorize the buyer's funds and settle the funds within 29 days.
Capture order `v2/checkout/orders/ORDER-ID/capture`	`POST`	This endpoint captures the funds for an order after the buyer approves the payment.
Confirm order `v2/checkout/orders/ORDER-ID/confirm-payment-source`	`POST`	The payer confirms their intent to pay for the order with the given payment source.
Show order details `v2/checkout/orders/ORDER-ID`	`GET`	This endpoint returns the order details. You can call this API at any stage in the order.
Update the order `v2/checkout/orders/ORDER-ID`	`PATCH`	Use this endpoint to make changes to an order. You can only update an order that is in the `CREATED` or `APPROVED` state. You can change the values of most fields in the payload, such as `intent`, or purchase unit fields like item information and shipping details. Supports the following operations: `add`, `remove`, and `replace`. Note: Not all operations are supported for every field.
Shipment tracking `v2/checkout/orders/ORDER-ID/track`	`POST`	Use this endpoint to add tracking information to an order, such as the carrier or other item details. You can also use this endpoint to manage user notifications.

Note: See the Orders v2 API use cases and samples for additional details about how the API works, other supported workflows, and sample requests.

Next steps

Explore other Orders v2 API use cases.