# Expanded Checkout Orders API use cases (/api/rest/integration/orders-api/api-use-cases/advanced) Learn about the [Expanded Checkout](/v5/expanded/overview/) workflow and use cases. ## What is an Expanded Checkout flow? [#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](/v5/apple-pay/integrate), [Google Pay](/v5/google-pay/integrate), and other [alternative payment methods](/payment-methods). ### Orders v2 API endpoints for Expanded Checkout flow [#orders-v2-api-endpoints-for-expanded-checkout-flow] ![Expanded flow](https://www.paypalobjects.com/ppdevdocs/orders-api/orders-api-advanced-flow.png) Learn more about the [Expanded Checkout](/v5/expanded/overview/) flow. > **Info:** **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](https://www.paypal.com/webapps/mpp/pci-compliance) page. ## Orders API flows using Expanded Checkout for Pay with PayPal [#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. > **Info:** **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 [#single-step-payment-flow] 1. Create the order: pass the advanced `payment_source` in the payload. 2. Shipment tracking for physical goods. ### Multi-step payment flow [#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 [#expanded-checkout-with-the-payment-source-in-a-create-order-request] 1. Create the order: pass the `payment_source` in the payload. 2. Payer action required: send the buyer to the **Review your purchase** page. 3. Capture or authorize payment. 4. Set up shipment tracking for physical goods. #### Expanded Checkout with the Confirm payment source endpoint [#expanded-checkout-with-the-confirm-payment-source-endpoint] 1. Create the order. 2. Confirm the payment source: pass the `payment_source` in the payload. 3. Payer action required: send the buyer to the **Review your purchase** page. 4. Capture order. 5. Set up shipment tracking for physical goods. #### Expanded Checkout with the Authorize order endpoint [#expanded-checkout-with-the-authorize-order-endpoint] 1. Create the order. 2. Payer action required: send the buyer to the **Review your purchase** page. 3. Authorize order. 4. Capture payment. 5. Set up shipment tracking for physical goods. ### Other API endpoints [#other-api-endpoints] 1. Update order details. 2. Show order details. > **Info:** **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 [#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](/api/rest/) section. This page also includes the complete Postman setup details. The [Orders Postman Collection](https://paypalcorp.postman.co/workspace/Test-Orders~269da256-27a0-4d00-9140-d9244798cb46/collection/31769881-80680620-c12a-4e9a-b496-a29cc1e9f1e8?action=share\&creator=31769881) has the latest API payloads for the Orders v2 API. > **Info:** **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 [#json-samples] ### Sample JSON order request 1: Single-step order flow [#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 [#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`. > **Info:** **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](/api/rest/requests/#http-request-headers) page. ```bash 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** ```json { "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 [#step-2-show-order-details] The Expanded Checkout flow doesn't need a payer action or buyer approval step. Make a [Show order details](/api/orders/v2/orders-get/) 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** ```bash 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** ```json { "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 [#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. > **Info:** **Note:** See the [Add tracking information for an > order](/api/orders/v2/orders-track-create/) endpoint of the Orders v2 API for > more information about each field in the payload. **Sample shipment tracking request** ```bash 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** ```json { "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" } ] } ``` > **Info:** **Note:** See [Integrate package > tracking](/api/orders-v2/track-orders/use) 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 [#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. 1. Create the order with basic cart details, in case you don't have the buyer's payment details upfront. 2. 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. 3. Set up the order flow with shipment tracking if you have physical goods. 4. Call the Show order details endpoint of the Orders v2 API at any stage to obtain the order details. #### Step 1: Create order [#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** ```bash 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** ```json { "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 [#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** ```bash 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** ```json { "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 [#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](/api/orders/v2/orders-get/) endpoint of the Orders v2 API. #### Step 4: Shipment tracking [#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. > **Info:** **Note:** See the [Add tracking information for an > order](/api/orders/v2/orders-track-create/) endpoint of the Orders v2 API for > more information about each field in the payload. **Sample shipment tracking request** ```bash 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** ```json { "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" } ] } ``` > **Info:** **Note:** See [Integrate package > tracking](/api/orders-v2/track-orders/use) 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 [#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 [#step-1-create-order-1] 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 [#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** ```bash 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 [#step-3-capture-authorized-payment] Capture the authorized payment by calling the [Capture authorized payment](/api/payments/v2/authorizations-capture/) 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. > **Info:** **Note:** > > The Payments capture is not the Order capture call. #### Step 4: Shipment tracking [#step-4-shipment-tracking-1] 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 [#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 [#step-1-create-order-2] Set the order `intent` to `CAPTURE`. A successful capture order request returns an HTTPS `201 Created` status code: **Sample capture order request** ```bash 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** ```json { "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 [#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. > **Info:** **Note:** > > The > > `payment_source` > > parameter is required. **Sample confirm payment request** ```bash 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** ```json { "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 [#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** ```bash 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** ```json { "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 [#step-4-shipment-tracking-2] 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 5: Multi-step order with 3D Secure contingency [#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`. > **Info:** **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](/api/orders/v2/#definition-card_verification). ```bash 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** ```json { "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.