Expanded Checkout Orders API use cases

Learn about the Expanded Checkout workflow and use cases.

What is an Expanded Checkout flow?

Buyers are not aware that PayPal is processing their payments.
The payment sources for these orders can be a card, Apple Pay , Google Pay , and other alternative payment methods .

Orders v2 API endpoints for Expanded Checkout flow

Expanded flow

Learn more about the Expanded Checkout flow.

Note: If you want to accept Expanded Checkout payment sources, such as credit or debt cards, you need to be PCI DSS compliant. For more information, see PayPal's PCI DSS Compliance page.

Orders API flows using Expanded Checkout for Pay with PayPal

This section uses a card as the payment source to showcase the possible Orders v2 API flows in an Expanded Checkout integration.

Note: All of the Orders v2 API endpoints are designed for merchants and partners. The payer only comes into picture during the buyer approval, or payer action required, step.

You need to pass an intent during the order creation. You can select either CAPTURE or AUTHORIZE:

CAPTURE : Use this intent to capture a payment immediately after the buyer approves the purchase.
AUTHORIZE : Use this option to authorize a buyer's funds before you capture payment and settle the purchase later. An authorization places a hold on the money and is valid for 29 days.

Single-step payment flow

Create the order: pass the advanced payment_source in the payload.
Shipment tracking for physical goods.

Multi-step payment flow

There are 3 different ways to complete an Expanded Checkout payment:

Expanded Checkout with the payment source in a Create order request

Create the order: pass the payment_source in the payload.
Payer action required: send the buyer to the Review your purchase page.
Capture or authorize payment.
Set up shipment tracking for physical goods.

Expanded Checkout with the Confirm payment source endpoint

Create the order.
Confirm the payment source: pass the payment_source in the payload.
Payer action required: send the buyer to the Review your purchase page.
Capture order.
Set up shipment tracking for physical goods.

Expanded Checkout with the Authorize order endpoint

Create the order.
Payer action required: send the buyer to the Review your purchase page.
Authorize order.
Capture payment.
Set up shipment tracking for physical goods.

Other API endpoints

Update order details.
Show order details.

Note: After you create an order, you have 3 hours to capture or modify that order. The order will remain in the CREATED state for only 3 hours. You can extend it up to 72 hours based on your use case. Connect with your TAM for more details.

Know before you code

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

The Orders Postman Collection has the latest API payloads for the Orders v2 API.

Note: Set up your server to make calls to the Orders v2 API instead of calling them directly from the browser or the client side.

JSON Samples

Sample JSON order request 1: Single-step order flow

This example uses a card as the payment source for a single-step order.

Step 1: Create and capture order

Set the order intent to AUTHORIZE or CAPTURE. A successful authorization request returns an HTTPS 200 OK status code. A successful capture request returns an HTTPS 201 Created status code.

Sample capture order request

This sample request passes CAPTURE as the order intent.

Note: Pass the idempotency header PayPal-Request-Id for this request. This unique, user-generated identifier stores server keys for 6 hours. The API callers can request the PayPal-Request-Id any number of times for up to 72 hours by speaking to their Account Manager. For more information about this header, refer to PayPal-Request-Id in the HTTP request headers section of the API Requests page.

Copy

Copied

curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/"
-H 'Content-Type: application/json'
-H 'Authorization: Bearer ACCESS-TOKEN'
-H 'PayPal-Request-Id: PAYPAL-REQUEST-ID'
-d '{
    "intent": "CAPTURE",
    "payment_source": {
        "card": {
           "number": "1111111111111111",
            "expiry": "2028-12",
            "name": "Firstname Lastname",
            "billing_address": {
                "address_line_1": "123 Main St.",
                "admin_area_1": "CA",
                "admin_area_2": "Anytown",
                "postal_code": "12345",
                "country_code": "US"
            }
        }
    },
    "purchase_units": [
        {
            "reference_id": "REFID-000-1001",
            "description": "Description of PU1",
            "custom_id": "CUSTOMID-1001",
            "soft_descriptor": "SOFT-1001",
            "amount": {
                "currency_code": "USD",
                "value": "100.00",
                "breakdown": {
                    "item_total": {
                        "currency_code": "USD",
                        "value": "100.00"
                    },
                    "shipping": {
                        "currency_code": "USD",
                        "value": "0"
                    },
                    "handling": {
                        "currency_code": "USD",
                        "value": "0"
                    },
                    "tax_total": {
                        "currency_code": "USD",
                        "value": "0"
                    },
                    "shipping_discount": {
                        "currency_code": "USD",
                        "value": "0"
                    }
                }
            },
            "items": [
                {
                    "name": "VRLens2",
                    "description": "VRLens2",
                    "sku": "259483234816",
                    "unit_amount": {
                        "currency_code": "USD",
                        "value": "50.00"
                    },
                    "tax": {
                        "currency_code": "USD",
                        "value": "0"
                    },
                    "quantity": "1",
                    "category": "PHYSICAL_GOODS"
                },
                 {
                    "name": "VRLens1",
                    "description": "VRLens1",
                    "sku": "259483234817",
                    "unit_amount": {
                        "currency_code": "USD",
                        "value": "50.00"
                    },
                    "tax": {
                        "currency_code": "USD",
                        "value": "0"
                    },
                    "quantity": "1",
                    "category": "PHYSICAL_GOODS"
                }
            ],
            "shipping": {
                "name": {
                    "full_name": "Firstname Lastname"
                },
                "address": {
                    "address_line_1": "123 Main St.",
                    "admin_area_2": "Anytown",
                    "admin_area_1": "CA",
                    "postal_code": "12345",
                    "country_code": "US"
                }
            }
        }
    ]
}'

Sample capture order response

Copy

Copied

{
    "id": "ORDER-ID",
    "status": "COMPLETED",
    "payment_source": {
        "card": {
            "name": "Firstname Lastname",
            "last_digits": "1111",
            "expiry": "2028-12",
            "brand": "VISA",
            "type": "UNKNOWN",
            "bin_details": {}
        }
    },
    "purchase_units": [
        {
            "reference_id": "REFID-000-1001",
            "amount": {
                "currency_code": "USD",
                "value": "100.00",
                "breakdown": {
                    "item_total": {
                        "currency_code": "USD",
                        "value": "100.00"
                    },
                    "shipping": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "handling": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "tax_total": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "insurance": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "shipping_discount": {
                        "currency_code": "USD",
                        "value": "0.00"
                    }
                }
            },
            "payee": {
                "email_address": "payee@example.com",
                "merchant_id": "MERCHANT-ID"
            },
            "description": "Description of PU1",
            "custom_id": "CUSTOMID-1001",
            "soft_descriptor": "SOFT-1001",
            "items": [
                {
                    "name": "VRLens2",
                    "unit_amount": {
                        "currency_code": "USD",
                        "value": "50.00"
                    },
                    "tax": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "quantity": "1",
                    "description": "VRLens2",
                    "sku": "259483234816",
                    "category": "PHYSICAL_GOODS"
                },
                {
                    "name": "VRLens1",
                    "unit_amount": {
                        "currency_code": "USD",
                        "value": "50.00"
                    },
                    "tax": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "quantity": "1",
                    "description": "VRLens1",
                    "sku": "259483234817",
                    "category": "PHYSICAL_GOODS"
                }
            ],
            "shipping": {
                "name": {
                    "full_name": "Firstname Lastname"
                },
                "address": {
                    "address_line_1": "123 Main St.",
                    "admin_area_2": "Anytown",
                    "admin_area_1": "CA",
                    "postal_code": "12345",
                    "country_code": "US"
                }
            },
            "payments": {
                "captures": [
                    {
                        "id": "CAPTURE-ID",
                        "status": "COMPLETED",
                        "amount": {
                            "currency_code": "USD",
                            "value": "100.00"
                        },
                        "final_capture": true,
                        "seller_protection": {
                            "status": "NOT_ELIGIBLE"
                        },
                        "seller_receivable_breakdown": {
                            "gross_amount": {
                                "currency_code": "USD",
                                "value": "100.00"
                            },
                            "paypal_fee": {
                                "currency_code": "USD",
                                "value": "3.08"
                            },
                            "net_amount": {
                                "currency_code": "USD",
                                "value": "96.92"
                            }
                        },
                        "custom_id": "CUSTOMID-1001",
                        "links": [
                            {
                                "href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID",
                                "rel": "self",
                                "method": "GET"
                            },
                            {
                                "href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID/refund",
                                "rel": "refund",
                                "method": "POST"
                            },
                            {
                                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                                "rel": "up",
                                "method": "GET"
                            }
                        ],
                        "create_time": "2024-04-05T23:04:53Z",
                        "update_time": "2024-04-05T23:04:53Z",
                        "network_transaction_reference": {
                            "id": "803050850126322",
                            "network": "VISA"
                        },
                        "processor_response": {
                            "avs_code": "A",
                            "cvv_code": "M",
                            "response_code": "0000"
                        }
                    }
                ]
            }
        }
    ],
    "create_time": "2024-04-05T23:04:53Z",
    "update_time": "2024-04-05T23:04:53Z",
    "links": [
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
            "rel": "self",
            "method": "GET"
        }
    ]
}

Step 2: Show order details

The Expanded Checkout flow doesn't need a payer action or buyer approval step. Make a Show order details call for an order by passing its order ID in a GET request to the v2/checkout/orders/ORDER_ID endpoint:

The API call returns the order status as COMPLETE .
The order includes the payment method details.

Sample show order details request

Copy

Copied

curl -v -X GET "https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID"
-H 'Authorization: Bearer ACCESS-TOKEN'

Sample show order details response

Copy

Copied

{
    "id": "ORDER-ID",
    "intent": "CAPTURE",
    "status": "COMPLETED",
    "payment_source": {
        "card": {
            "name": "Firstname Lastname",
            "last_digits": "1111",
            "expiry": "2028-12",
            "brand": "VISA",
            "type": "UNKNOWN",
            "bin_details": {}
        }
    },
    "purchase_units": [
        {
            "reference_id": "REFID-000-1001",
            "amount": {
                "currency_code": "USD",
                "value": "100.00",
                "breakdown": {
                    "item_total": {
                        "currency_code": "USD",
                        "value": "100.00"
                    },
                    "shipping": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "handling": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "tax_total": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "insurance": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "shipping_discount": {
                        "currency_code": "USD",
                        "value": "0.00"
                    }
                }
            },
            "payee": {
                "email_address": "payee@example.com",
                "merchant_id": "MERCHANT-ID"
            },
            "description": "Description of PU1",
            "custom_id": "CUSTOMID-1001",
            "soft_descriptor": "SOFT-1001",
            "items": [
                {
                    "name": "VRLens2",
                    "unit_amount": {
                        "currency_code": "USD",
                        "value": "50.00"
                    },
                    "tax": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "quantity": "1",
                    "description": "VRLens2",
                    "sku": "259483234816",
                    "category": "PHYSICAL_GOODS"
                },
                {
                    "name": "VRLens1",
                    "unit_amount": {
                        "currency_code": "USD",
                        "value": "50.00"
                    },
                    "tax": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "quantity": "1",
                    "description": "VRLens1",
                    "sku": "259483234817",
                    "category": "PHYSICAL_GOODS"
                }
            ],
            "shipping": {
                "name": {
                    "full_name": "Firstname Lastname"
                },
                "address": {
                    "address_line_1": "123 Main St.",
                    "admin_area_2": "Anytown",
                    "admin_area_1": "CA",
                    "postal_code": "12345",
                    "country_code": "US"
                }
            },
            "payments": {
                "captures": [
                    {
                        "id": "CAPTURE-ID",
                        "status": "COMPLETED",
                        "amount": {
                            "currency_code": "USD",
                            "value": "100.00"
                        },
                        "final_capture": true,
                        "seller_protection": {
                            "status": "NOT_ELIGIBLE"
                        },
                        "seller_receivable_breakdown": {
                            "gross_amount": {
                                "currency_code": "USD",
                                "value": "100.00"
                            },
                            "paypal_fee": {
                                "currency_code": "USD",
                                "value": "3.08"
                            },
                            "net_amount": {
                                "currency_code": "USD",
                                "value": "96.92"
                            }
                        },
                        "custom_id": "CUSTOMID-1001",
                        "links": [
                            {
                                "href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID",
                                "rel": "self",
                                "method": "GET"
                            },
                            {
                                "href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID/refund",
                                "rel": "refund",
                                "method": "POST"
                            },
                            {
                                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                                "rel": "up",
                                "method": "GET"
                            }
                        ],
                        "create_time": "2024-04-05T23:04:53Z",
                        "update_time": "2024-04-05T23:04:53Z",
                        "network_transaction_reference": {
                            "id": "803050850126322",
                            "network": "VISA"
                        },
                        "processor_response": {
                            "avs_code": "A",
                            "cvv_code": "M",
                            "response_code": "0000"
                        }
                    }
                ]
            }
        }
    ],
    "create_time": "2024-04-05T23:04:53Z",
    "update_time": "2024-04-05T23:04:53Z",
    "links": [
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
            "rel": "self",
            "method": "GET"
        }
    ]
}

Step 3: Shipment tracking

Consider adding this step if you have physical goods in your order. Use this Add tracking information endpoint of the Orders v2 API to add tracking information to your packages, such as carrier, item, and SKU details.

If the intent is set to CAPTURE, replace CAPTURE_ID with the payments.captures.id field that is found in the Order capture's API response.

If the intent is set to AUTHORIZE, replace CAPTURE_ID with the ID field found in the Payment capture’s API response, not the Order capture's API call.

The capture_id field is automatically populated if you're using the PayPal Postman collection.

Note: See the Add tracking information for an order endpoint of the Orders v2 API for more information about each field in the payload.

Sample shipment tracking request

Copy

Copied

curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/track"
-H 'Content-Type: application/json'
-H 'Authorization: Bearer ACCESS-TOKEN'
-d '{
  "capture_id": "CAPTURE-ID",
  "tracking_number": "TRACKING-ID",
  "carrier": "FEDEX",
  "notify_payer": false,
  "items": [
    {
      "upc": {
        "type": "UPC-A",
        "code": "upc001"
      },
      "image_url": "https://www.example.com/example.jpg",
      "url": "https://www.example.com/example",
      "name": "VRLens2",
                    "unit_amount": {
                        "currency_code": "USD",
                        "value": "50.00"
                    },
                    "tax": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "quantity": "1",
                    "description": "VRLens2",
                    "sku": "259483234816",
                    "category": "PHYSICAL_GOODS"
    },
    {
      "upc": {
        "type": "UPC-B",
        "code": "upc002"
      },
      "image_url": "https://www.example1.com/example.jpg",
      "url": "https://www.example.com/example",
      "name": "VRLens1",
                    "unit_amount": {
                        "currency_code": "USD",
                        "value": "50.00"
                    },
                    "tax": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "quantity": "1",
                    "description": "VRLens1",
                    "sku": "259483234817",
                    "category": "PHYSICAL_GOODS"
    }
  ]
}'

Sample shipment tracking response

Copy

Copied

{
    "id": "ORDER-ID",
    "intent": "CAPTURE",
    "status": "COMPLETED",
    "payment_source": {
        "card": {
            "name": "Firstname Lastname",
            "last_digits": "1111",
            "expiry": "2028-12",
            "brand": "VISA",
            "type": "UNKNOWN",
            "bin_details": {}
        }
    },
    "purchase_units": [
        {
            "reference_id": "REFID-000-1001",
            "amount": {
                "currency_code": "USD",
                "value": "100.00"
            },
            "payee": {
                "email_address": "payee@example.com",
                "merchant_id": "MERCHANT-ID"
            },
            "soft_descriptor": "TEST STORE",
            "shipping": {
                "address": {
                    "address_line_1": "123 Main St.",
                    "admin_area_2": "Anytown",
                    "admin_area_1": "CA",
                    "postal_code": "12345",
                    "country_code": "US"
                },
                "trackers": [
                    {
                        "id": "TRACKING-ID",
                        "items": [
                            {
                                "name": "VRLens2",
                                "sku": "259483234816",
                                "quantity": "1",
                                "image_url": "https://www.example.com/example.jpg",
                                "upc": {
                                    "type": "UPC-A",
                                    "code": "upc001"
                                },
                                "url": "https://www.example.com/example"
                            },
                            {
                                "name": "VRLens1",
                                "sku": "259483234817",
                                "quantity": "1",
                                "image_url": "https://www.example1.com/example.jpg",
                                "upc": {
                                    "type": "UPC-B",
                                    "code": "upc002"
                                },
                                "url": "https://www.example.com/example"
                            }
                        ],
                        "links": [
                            {
                                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                                "rel": "up",
                                "method": "GET"
                            },
                            {
                                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/trackers/TRACKING-ID",
                                "rel": "update",
                                "method": "PATCH"
                            }
                        ],
                        "status": "SHIPPED"
                    }
                ]
            },
            "payments": {
                "captures": [
                    {
                        "id": "CAPTURE-ID",
                        "status": "COMPLETED",
                        "amount": {
                            "currency_code": "USD",
                            "value": "100.00"
                        },
                        "final_capture": true,
                        "disbursement_mode": "INSTANT",
                        "seller_protection": {
                            "status": "NOT_ELIGIBLE"
                        },
                        "seller_receivable_breakdown": {
                            "gross_amount": {
                                "currency_code": "USD",
                                "value": "100.00"
                            },
                            "paypal_fee": {
                                "currency_code": "USD",
                                "value": "3.08"
                            },
                            "net_amount": {
                                "currency_code": "USD",
                                "value": "96.92"
                            }
                        },
                        "links": [
                            {
                                "href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID",
                                "rel": "self",
                                "method": "GET"
                            },
                            {
                                "href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID/refund",
                                "rel": "refund",
                                "method": "POST"
                            },
                            {
                                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                                "rel": "up",
                                "method": "GET"
                            }
                        ],
                        "create_time": "2024-04-06T04:27:17Z",
                        "update_time": "2024-04-06T04:27:17Z",
                        "network_transaction_reference": {
                            "id": "188683214344810",
                            "network": "VISA"
                        },
                        "processor_response": {
                            "avs_code": "A",
                            "cvv_code": "M",
                            "response_code": "0000"
                        }
                    }
                ]
            }
        }
    ],
    "create_time": "2024-04-06T04:27:15Z",
    "update_time": "2024-04-06T04:27:17Z",
    "links": [
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
            "rel": "self",
            "method": "GET"
        }
    ]
}

Note: See Integrate package tracking for more details about adding package tracking numbers to your orders with the Orders v2 API.

Sample JSON order request 2: Multi-step order flow with Capture order endpoint

The following sample uses a card as the payment source for a multi-step order. When you don't have the buyer's payment details upfront, create the order with non-transactional information, such as the cart details, and update the order with the payment details after you collect them from the buyer.

Create the order with basic cart details, in case you don't have the buyer's payment details upfront.
After creating the order, collect the buyer's payment details on your application or website. After you get the buyer's payment details, call the Capture payment for order endpoint of the Orders v2 API with the payment source information in the payload. If the payment is successful, the order moves to the COMPLETED state.
Set up the order flow with shipment tracking if you have physical goods.
Call the Show order details endpoint of the Orders v2 API at any stage to obtain the order details.

Step 1: Create order

Set the order intent to CAPTURE. A successful capture order request returns an HTTPS 201 Created status code:

Sample capture order request

Copy

Copied

curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/"
-H 'Content-Type: application/json'
-H 'Authorization: Bearer ACCESS-TOKEN'
-H 'PayPal-Request-Id: PAYPAL-REQUEST-ID'
-d '{
    "intent": "CAPTURE",
    "purchase_units": [
        {
            "items": [
                {
                    "name": "T-Shirt",
                    "description": "Green XL",
                    "quantity": "1",
                    "unit_amount": {
                        "currency_code": "USD",
                        "value": "100.00"
                    }
                }
            ],
            "amount": {
                "currency_code": "USD",
                "value": "100.00",
                "breakdown": {
                    "item_total": {
                        "currency_code": "USD",
                        "value": "100.00"
                    }
                }
            }
        }
    ]
}'

Sample capture order response

Copy

Copied

{
    "id": "ORDER-ID",
    "status": "CREATED",
    "links": [
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
            "rel": "self",
            "method": "GET"
        },
        {
            "href": "https://www.sandbox.paypal.com/checkoutnow?token=ORDER-ID",
            "rel": "approve",
            "method": "GET"
        },
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
            "rel": "update",
            "method": "PATCH"
        },
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/capture",
            "rel": "capture",
            "method": "POST"
        }
    ]
}

Step 2: Capture payment

If you include the payment source in the request, this capture payment call will complete the order.

Sample capture payment request

Copy

Copied

curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/capture"
-H 'Content-Type: application/json'
-H 'Authorization: Bearer ACCESS-TOKEN'
-d '{
    "payment_source": {
        "card": {
            "number": "1111111111111111",
            "expiry": "2028-12",
            "name": "Firstname Lastname",
            "billing_address": {
                "address_line_1": "123 Main St.",
                "admin_area_1": "CA",
                "admin_area_2": "Anytown",
                "postal_code": "12345",
                "country_code": "US"
            },
            "attributes": {
                "customer": {
                    "email_address": "payer@example.com",
                    "phone": {
                        "phone_number": {
                            "national_number": "5555555555"
                        }
                    }
                }
            }
        }
    }
}'

Sample capture payment response

Copy

Copied

{
    "id": "ORDER-ID",
    "intent": "CAPTURE",
    "status": "COMPLETED",
    "payment_source": {
        "card": {
            "name": "Firstname Lastname",
            "last_digits": "5734",
            "expiry": "2028-12",
            "brand": "VISA",
            "available_networks": [
                "VISA"
            ],
            "type": "CREDIT",
            "bin_details": {
                "bin": "403203",
                "issuing_bank": "Baxter Credit Union",
                "bin_country_code": "US"
            }
        }
    },
    "purchase_units": [
        {
            "reference_id": "REFID-000-1001",
            "amount": {
                "currency_code": "USD",
                "value": "100.00",
                "breakdown": {
                    "item_total": {
                        "currency_code": "USD",
                        "value": "100.00"
                    },
                    "shipping": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "handling": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "insurance": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "shipping_discount": {
                        "currency_code": "USD",
                        "value": "0.00"
                    }
                }
            },
            "payee": {
                "email_address": "payee@example.com",
                "merchant_id": "MERCHANT-ID"
            },
            "description": "T-Shirt",
            "soft_descriptor": "TEST STORE",
            "items": [
                {
                    "name": "T-Shirt",
                    "unit_amount": {
                        "currency_code": "USD",
                        "value": "100.00"
                    },
                    "tax": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "quantity": "1",
                    "description": "Green XL"
                }
            ],
            "payments": {
                "captures": [
                    {
                        "id": "CAPTURE-ID",
                        "status": "COMPLETED",
                        "amount": {
                            "currency_code": "USD",
                            "value": "100.00"
                        },
                        "final_capture": true,
                        "seller_protection": {
                            "status": "NOT_ELIGIBLE"
                        },
                        "seller_receivable_breakdown": {
                            "gross_amount": {
                                "currency_code": "USD",
                                "value": "100.00"
                            },
                            "paypal_fee": {
                                "currency_code": "USD",
                                "value": "3.08"
                            },
                            "net_amount": {
                                "currency_code": "USD",
                                "value": "96.92"
                            }
                        },
                        "links": [
                            {
                                "href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID",
                                "rel": "self",
                                "method": "GET"
                            },
                            {
                                "href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID/refund",
                                "rel": "refund",
                                "method": "POST"
                            },
                            {
                                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                                "rel": "up",
                                "method": "GET"
                            }
                        ],
                        "create_time": "2024-03-20T17:53:10Z",
                        "update_time": "2024-03-20T17:53:10Z",
                        "network_transaction_reference": {
                            "id": "368694990810273",
                            "network": "VISA"
                        },
                        "processor_response": {
                            "avs_code": "A",
                            "cvv_code": "M",
                            "response_code": "0000"
                        }
                    }
                ]
            }
        }
    ],
    "create_time": "2024-03-20T17:53:10Z",
    "update_time": "2024-03-20T17:53:10Z",
    "links": [
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
            "rel": "self",
            "method": "GET"
        }
    ]
}

Step 3: Show order details

The Capture payment request moves an order to the COMPLETED state. You can get the complete order information for an order in any state by sending a GET call and the order ID to the Show order details endpoint of the Orders v2 API.

Step 4: Shipment tracking

If you have physical goods in your order, you can use the Shipment Tracking API to add tracking information to your packages, such as carrier, item, and SKU details.

If the intent is set to CAPTURE, replace CAPTURE_ID with the payments.captures.id field that is found in the Order capture's API response.

If the intent is set to AUTHORIZE, replace CAPTURE_ID with the ID field found in the Payment capture API response, not the Order API’s capture call.

The capture_id field is automatically populated if you're using the PayPal Postman collection.

Note: See the Add tracking information for an order endpoint of the Orders v2 API for more information about each field in the payload.

Sample shipment tracking request

Copy

Copied

curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/track"
-H 'Content-Type: application/json'
-H 'Authorization: Bearer ACCESS-TOKEN'
-d '{
  "capture_id": "CAPTURE-ID",
  "tracking_number": "TRACKING-ID",
  "carrier": "FEDEX",
  "notify_payer": false,
  "items": [
    {
      "upc": {
        "type": "UPC-A",
        "code": "upc001"
      },
      "image_url": "https://www.example.com/example.jpg",
      "url": "https://www.example.com/example",
      "name": "VRLens2",
                    "unit_amount": {
                        "currency_code": "USD",
                        "value": "50.00"
                    },
                    "tax": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "quantity": "1",
                    "description": "VRLens2",
                    "sku": "259483234816",
                    "category": "PHYSICAL_GOODS"
    },
    {
      "upc": {
        "type": "UPC-B",
        "code": "upc002"
      },
      "image_url": "https://www.example1.com/example.jpg",
      "url": "https://www.example.com/example",
      "name": "VRLens1",
                    "unit_amount": {
                        "currency_code": "USD",
                        "value": "50.00"
                    },
                    "tax": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "quantity": "1",
                    "description": "VRLens1",
                    "sku": "259483234817",
                    "category": "PHYSICAL_GOODS"
    }
  ]
}'

Sample shipment tracking response

Copy

Copied

{
    "id": "ORDER-ID",
    "intent": "CAPTURE",
    "status": "COMPLETED",
    "payment_source": {
        "card": {
            "name": "Firstname Lastname",
            "last_digits": "1111",
            "expiry": "2028-12",
            "brand": "VISA",
            "type": "UNKNOWN",
            "bin_details": {}
        }
    },
    "purchase_units": [
        {
            "reference_id": "REFID-000-1001",
            "amount": {
                "currency_code": "USD",
                "value": "100.00"
            },
            "payee": {
                "email_address": "payee@example.com",
                "merchant_id": "MERCHANT-ID"
            },
            "soft_descriptor": "TEST STORE",
            "shipping": {
                "address": {
                    "address_line_1": "123 Main St.",
                    "admin_area_2": "Anytown",
                    "admin_area_1": "CA",
                    "postal_code": "12345",
                    "country_code": "US"
                },
                "trackers": [
                    {
                        "id": "TRACKING-ID",
                        "items": [
                            {
                                "name": "VRLens2",
                                "sku": "259483234816",
                                "quantity": "1",
                                "image_url": "https://www.example.com/example.jpg",
                                "upc": {
                                    "type": "UPC-A",
                                    "code": "upc001"
                                },
                                "url": "https://www.example.com/example"
                            },
                            {
                                "name": "VRLens1",
                                "sku": "259483234817",
                                "quantity": "1",
                                "image_url": "https://www.example1.com/example.jpg",
                                "upc": {
                                    "type": "UPC-B",
                                    "code": "upc002"
                                },
                                "url": "https://www.example.com/example"
                            }
                        ],
                        "links": [
                            {
                                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                                "rel": "up",
                                "method": "GET"
                            },
                            {
                                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/trackers/TRACKING-ID",
                                "rel": "update",
                                "method": "PATCH"
                            }
                        ],
                        "status": "SHIPPED"
                    }
                ]
            },
            "payments": {
                "captures": [
                    {
                        "id": "CAPTURE-ID",
                        "status": "COMPLETED",
                        "amount": {
                            "currency_code": "USD",
                            "value": "100.00"
                        },
                        "final_capture": true,
                        "disbursement_mode": "INSTANT",
                        "seller_protection": {
                            "status": "NOT_ELIGIBLE"
                        },
                        "seller_receivable_breakdown": {
                            "gross_amount": {
                                "currency_code": "USD",
                                "value": "100.00"
                            },
                            "paypal_fee": {
                                "currency_code": "USD",
                                "value": "3.08"
                            },
                            "net_amount": {
                                "currency_code": "USD",
                                "value": "96.92"
                            }
                        },
                        "links": [
                            {
                                "href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID",
                                "rel": "self",
                                "method": "GET"
                            },
                            {
                                "href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID/refund",
                                "rel": "refund",
                                "method": "POST"
                            },
                            {
                                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                                "rel": "up",
                                "method": "GET"
                            }
                        ],
                        "create_time": "2024-04-06T04:27:17Z",
                        "update_time": "2024-04-06T04:27:17Z",
                        "network_transaction_reference": {
                            "id": "188683214344810",
                            "network": "VISA"
                        },
                        "processor_response": {
                            "avs_code": "A",
                            "cvv_code": "M",
                            "response_code": "0000"
                        }
                    }
                ]
            }
        }
    ],
    "create_time": "2024-04-06T04:27:15Z",
    "update_time": "2024-04-06T04:27:17Z",
    "links": [
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
            "rel": "self",
            "method": "GET"
        }
    ]
}

Note: See Integrate package tracking for more details about adding package tracking numbers to your orders with the Orders v2 API.

Sample JSON order request 3: Multi-step order flow with Authorize order endpoint

This flow is similar to the preceding example when you don't have the buyer’s payment details upfront while creating the order. Create the order with non-transactional information such as the cart details, collect the authorization from the buyer, and call the Capture payment for order endpoint of the Orders v2 API with the payment details when the order is ready. For example, the buyer can pay only after the order is shipped.

Create the order with basic cart details, in case you don't have the buyer's payment details upfront.

After creating the order, collect the buyer's payment details on your application or website. After you get the buyer's payment details, call the Authorize API with the payment source information in the payload to obtain the buyer's authorization. This authorization is valid for 29 days.

Call the Capture payment for order endpoint of the Orders v2 API when you want to charge the buyer and capture the payment. If the payment is successful, the order moves to the COMPLETED state.

Set up the order flow with shipment tracking if you have physical goods.

Call the Show order details endpoint of the Orders v2 API at any stage to obtain the order details.

Step 1: Create order

Set the order intent to AUTHORIZE. A successful authorize order request returns an HTTPS 201 Created status code.

Refer to the Sample capture order request in Step 1: Create order in the preceding Sample JSON order request 2: Multi-step order flow with Capture order endpoint. Change the intent from CAPTURE to AUTHORIZE.

Step 2: Authorize order

An Authorize order request accepts payment_source as an optional input, like a Capture order request. The response returns an HTTPS 201 Created status code and a JSON response body that shows the authorized payment details. The id field in the response passes the authorization ID.

Sample authorize order request

Copy

Copied

curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/authorize"
-H 'Content-Type: application/json'
-H 'Authorization: Bearer ACCESS-TOKEN'
-d '{
    "payment_source": {
        "card": {
            "number": "1111111111111111",
            "expiry": "2028-12",
            "name": "Firstname Lastname",
            "billing_address": {
                "address_line_1": "123 Main St.",
                "admin_area_1": "CA",
                "admin_area_2": "Anytown",
                "postal_code": "12345",
                "country_code": "US"
            },
            "attributes": {
                "customer": {
                    "email_address": "payer@example.com",
                    "phone": {
                        "phone_number": {
                            "national_number": "5555555555"
                        }
                    }
                }
            }
        }
    }
}'

Step 3: Capture authorized payment

Capture the authorized payment by calling the Capture authorized payment endpoint of the Payments v2 API using a POST request to /v2/payments/authorizations/AUTHORIZATION-ID/capture. Replace AUTHORIZATION-ID with the authorization ID returned in Step 2: Authorize order. This step triggers a call to the payment gateway to capture the payment.

Note: The Payments capture is not the Order capture call.

Step 4: Shipment tracking

If you have physical goods in your order, you can use the Shipment Tracking API to add tracking information to your packages, such as carrier, item, and SKU details. For more information, refer to the Shipment tracking steps in the preceding Sample JSON order request 1: Single-step order flow and Sample JSON order request 2: Multi-step order flow with Capture order endpoint sections.

Sample JSON order request 4: Multi-step with Confirm payment source endpoint

This example also demonstrates another variant of the multi-step order creation: using a card as the payment source. You can create the order without any payment source and then use the Confirm the Order endpoint of the Orders v2 API to confirm the buyer's intent to pay with that card. Depending on your chosen intent, payment capture will be immediate or in the future, similar to the preceding examples.

Step 1: Create order

Set the order intent to CAPTURE. A successful capture order request returns an HTTPS 201 Created status code:

Sample capture order request

Copy

Copied

curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/"
-H 'Content-Type: application/json'
-H 'Authorization: Bearer ACCESS-TOKEN'
-H 'PayPal-Request-Id: PAYPAL-REQUEST-ID'
-d '{
    "intent": "CAPTURE",
    "purchase_units": [
        {
            "items": [
                {
                    "name": "T-Shirt",
                    "description": "Green XL",
                    "quantity": "1",
                    "unit_amount": {
                        "currency_code": "USD",
                        "value": "100.00"
                    }
                }
            ],
            "amount": {
                "currency_code": "USD",
                "value": "100.00",
                "breakdown": {
                    "item_total": {
                        "currency_code": "USD",
                        "value": "100.00"
                    }
                }
            }
        }
    ]
}'

Sample capture order response

Copy

Copied

{
    "id": "ORDER-ID",
    "status": "CREATED",
    "links": [
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
            "rel": "self",
            "method": "GET"
        },
        {
            "href": "https://www.sandbox.paypal.com/checkoutnow?token=ORDER-ID",
            "rel": "approve",
            "method": "GET"
        },
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
            "rel": "update",
            "method": "PATCH"
        },
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/capture",
            "rel": "capture",
            "method": "POST"
        }
    ]
}

Step 2: Confirm payment

The buyer can confirm their intent to pay for the order using an Expanded Checkout payment source: in this case, a card.

Note: The payment_source parameter is required.

Sample confirm payment request

Copy

Copied

curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/confirm-payment-source"
-H 'Authorization: Bearer ACCESS-TOKEN'
-d '{
    "payment_source": {
        "card": {
            "number": "1111111111111111",
            "expiry": "2028-12",
            "name": "Firstname Lastname",
            "billing_address": {
                "address_line_1": "123 Main St.",
                "admin_area_1": "CA",
                "admin_area_2": "Anytown",
                "postal_code": "12345",
                "country_code": "US"
            },
            "attributes": {
                "customer": {
                    "email_address": "payer@example.com",
                    "phone": {
                        "phone_number": {
                            "national_number": "5555555555"
                        }
                    }
                }
            }
        }
    }
}'

Sample confirm payment response

Copy

Copied

{
    "id": "ORDER-ID",
    "intent": "CAPTURE",
    "status": "APPROVED",
    "payment_source": {
        "card": {
            "name": "Firstname Lastname",
            "last_digits": "5734",
            "expiry": "2028-12",
            "brand": "VISA",
            "available_networks": [
                "VISA"
            ],
            "type": "CREDIT",
            "bin_details": {
                "bin": "403203",
                "issuing_bank": "Baxter Credit Union",
                "bin_country_code": "US"
            }
        }
    },
    "purchase_units": [
        {
            "reference_id": "REFID-000-1001",
            "amount": {
                "currency_code": "USD",
                "value": "100.00",
                "breakdown": {
                    "item_total": {
                        "currency_code": "USD",
                        "value": "100.00"
                    }
                }
            },
            "payee": {
                "email_address": "payee@example.com",
                "merchant_id": "MERCHANT-ID"
            },
            "items": [
                {
                    "name": "T-Shirt",
                    "unit_amount": {
                        "currency_code": "USD",
                        "value": "100.00"
                    },
                    "quantity": "1",
                    "description": "Green XL",
                    "category": "PHYSICAL_GOODS"
                }
            ]
        }
    ],
    "links": [
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
            "rel": "self",
            "method": "GET"
        },
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/capture",
            "rel": "capture",
            "method": "POST"
        }
    ]
}

Unlike the PayPal Checkout flows, explicit buyer approval is not required for cards or any Expanded Checkout payments.

Step 3: Capture payment

The last step to complete the order is to capture the payment. You can capture an order without any payment source information because you already specified a payment source in Step 2: Confirm payment.

Sample capture payment request

Copy

Copied

curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/capture"
-H 'Content-Type: application/json'
-H 'Authorization: Bearer ACCESS-TOKEN'
-d '{}'

Sample capture payment response

Copy

Copied

{
    "id": "ORDER-ID",
    "intent": "CAPTURE",
    "status": "COMPLETED",
    "payment_source": {
        "card": {
            "name": "Firstname Lastname",
            "last_digits": "5734",
            "expiry": "2028-12",
            "brand": "VISA",
            "available_networks": [
                "VISA"
            ],
            "type": "CREDIT",
            "bin_details": {
                "bin": "403203",
                "issuing_bank": "Baxter Credit Union",
                "bin_country_code": "US"
            }
        }
    },
    "purchase_units": [
        {
            "reference_id": "REFID-000-1001",
            "amount": {
                "currency_code": "USD",
                "value": "100.00",
                "breakdown": {
                    "item_total": {
                        "currency_code": "USD",
                        "value": "100.00"
                    },
                    "shipping": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "handling": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "insurance": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "shipping_discount": {
                        "currency_code": "USD",
                        "value": "0.00"
                    }
                }
            },
            "payee": {
                "email_address": "payee@example.com",
                "merchant_id": "MERCHANT-ID"
            },
            "description": "T-Shirt",
            "soft_descriptor": "TEST STORE",
            "items": [
                {
                    "name": "T-Shirt",
                    "unit_amount": {
                        "currency_code": "USD",
                        "value": "100.00"
                    },
                    "tax": {
                        "currency_code": "USD",
                        "value": "0.00"
                    },
                    "quantity": "1",
                    "description": "Green XL",
                    "category": "PHYSICAL_GOODS"
                }
            ],
            "payments": {
                "captures": [
                    {
                        "id": "94F67165DM5675019",
                        "status": "COMPLETED",
                        "amount": {
                            "currency_code": "USD",
                            "value": "100.00"
                        },
                        "final_capture": true,
                        "seller_protection": {
                            "status": "NOT_ELIGIBLE"
                        },
                        "seller_receivable_breakdown": {
                            "gross_amount": {
                                "currency_code": "USD",
                                "value": "100.00"
                            },
                            "paypal_fee": {
                                "currency_code": "USD",
                                "value": "3.08"
                            },
                            "net_amount": {
                                "currency_code": "USD",
                                "value": "96.92"
                            }
                        },
                        "links": [
                            {
                                "href": "https://api.sandbox.paypal.com/v2/payments/captures/94F67165DM5675019",
                                "rel": "self",
                                "method": "GET"
                            },
                            {
                                "href": "https://api.sandbox.paypal.com/v2/payments/captures/94F67165DM5675019/refund",
                                "rel": "refund",
                                "method": "POST"
                            },
                            {
                                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
                                "rel": "up",
                                "method": "GET"
                            }
                        ],
                        "create_time": "2024-04-08T14:44:54Z",
                        "update_time": "2024-04-08T14:44:54Z",
                        "network_transaction_reference": {
                            "id": "476436918458866",
                            "network": "VISA"
                        },
                        "processor_response": {
                            "avs_code": "A",
                            "cvv_code": "M",
                            "response_code": "0000"
                        }
                    }
                ]
            }
        }
    ],
    "create_time": "2024-04-08T14:44:54Z",
    "update_time": "2024-04-08T14:44:54Z",
    "links": [
        {
            "href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
            "rel": "self",
            "method": "GET"
        }
    ]
}

Step 4: Shipment tracking

Sample JSON order request 5: Multi-step order with 3D Secure contingency

This example includes instructions to apply strong customer authentication (SCA) to the transaction. Merchants can use this setting as another layer of security.

When the request comes from a country that requires SCA, the response returns a contingency and a HATEOAS link. The API caller, usually the merchant, should redirect the payer to that link so the payer can authenticate themselves for their issuing bank or other entity.

The HATEOAS link is only available in regions that support SCA, such as European countries. When authorization is requested, the response includes the AVS/CVV results.

Sample create order request

This request is similar to the single-step order flow. Pass the flag SCA_WHEN_REQUIRED in payment_source.card.attributes.verification.method.

Note: Find out more about the values that payment_source.card.attributes.verification accepts by visiting the Card verification section of the Orders v2 API.

Copy

Copied

curl -v -X POST "https://api-m.sandbox.paypal.com/v2/checkout/orders/"
-H 'Content-Type: application/json'
-H 'Authorization: Bearer ACCESS-TOKEN'
-H 'PayPal-Request-Id: PAYPAL-REQUEST-ID'
-d '{
            "intent": "CAPTURE",
            "purchase_units": [
                {
                    "amount": {
                        "currency_code": "USD",
                        "value": "100.00"
                    }
                }
            ],
            "payment_source": {
                "card": {
                    "number": "1111111111111111",
                    "expiry": "2028-12",
                    "name": "Firstname Lastname",
                    "billing_address": {
                        "address_line_1": "123 Main St.",
                        "admin_area_1": "CA",
                        "admin_area_2": "Anytown",
                        "postal_code": "12345",
                        "country_code": "US"
                    },
                    "attributes": {
                        "verification": {
                            "method": "SCA_WHEN_REQUIRED"
                        }
                    }
                }
            }
    }'

Sample create order response

Copy

Copied

{
            "id": "ORDER-ID",
            "status": "PAYER_ACTION_REQUIRED",
            "purchase_units": [
                {
                    "reference_id": "REFID-000-1001"
                }
            ],
            "links": [
                {
                    "href": "https://api.paypal.com/v2/checkout/orders/ORDER-ID",
                    "rel": "self",
                    "method": "GET"
                },
                {
                    "href": "https://www.paypal.com/checkoutnow?token=ORDER-ID&exp_flow=authenticate",
                    "rel": "payer-action",
                    "method": "GET"
                }
            ]
}

Similar to the PayPal Checkout flows, the merchant needs to redirect the buyer to the payer-action HATEOS link found in the order creation response. This can be any merchant-controlled bank or payment page for additional approval, such as one-time passwords.

See the Authorize order, Capture payment, Show order details, and Shipment tracking steps in the preceding examples for the remaining steps needed for an Expanded Checkout payment.