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.

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

1. The buyer looks through the items on the merchant's site and adds an item to their cart.
2. The buyer goes to check out, and selects the PayPal button.
3. 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.
4. The merchant redirects the buyer to the approval URL.
5. The buyer sees a payment page with various payment options, such as credit card or PayPal.
6. The buyer chooses a payment method and approves the order.
7. The buyer is redirected to the return URL from the original Create order API call from step 3.
8. 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

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

API endpoints

Next steps

Explore other Orders v2 API use cases.

See also

View common errors returned by the Orders v2 API endpoints.