Checkout

​

Checkout Flow

This guide walks you through the process of converting a customer’s shopping cart into a placed order, including address validation, shipping checks, payment processing, and handling payment retries. It utilizes endpoints primarily from the Carts, Orders, Payments, Shipping, and Common modules.

Prerequisites:

• A valid cart_id representing the customer’s cart with items added.
• A valid user session token (access_token), which can be for an anonymous or logged-in user.

High-Level Steps:

1. Review Cart: Display the final cart contents and totals.
2. Collect Addresses: Gather or confirm billing and shipping addresses.
3. Validate Pincode Serviceability: Check if shipping is available to the destination.
4. (Optional) Apply Discounts/Credits: Allow final application of coupons, loyalty points, or credit balance.
5. Create Order & Initiate Payment: Send the cart details to create an order and get payment instructions.
6. Process Payment: Redirect user or use SDKs to complete payment via the chosen gateway (Juspay recommended).
7. Handle Payment Callback/Redirect: User returns to your site from the payment gateway.
8. Verify Payment Status: Poll the Commerce Engine API to confirm the final payment status.
9. Display Confirmation/Failure: Show the appropriate order confirmation or payment failure/retry screen.

​

Step 1: Review Cart

Before proceeding, ensure the customer can review their cart. Fetch the latest cart state:

• GET /carts/{cart_id} or GET /carts/users/{user_id}
• Display cart_items, pricing breakdown (subtotal, tax, shipping, grand_total), applied discounts (coupon_code, loyalty_points_redeemed, etc.), and the final to_be_paid amount.

​

Step 2: Collect & Update Addresses

Accurate addresses are required for tax calculation, shipping cost determination, and delivery.

• Logged-in Users:

  • Fetch saved addresses using GET /customers/{user_id}/addresses.

  • Allow the user to select existing billing and shipping addresses or add a new one (POST /customers/{user_id}/addresses).

  • Update the cart with the selected address IDs using POST /carts/{id}/address:

    {
      "billing_address_id": "SAVED_ADDRESS_ID_1",
      "shipping_address_id": "SAVED_ADDRESS_ID_2"
    }
    

• Anonymous / Guest Users:

  • Provide forms to collect billing and shipping address details.

  • Use GET /common/countries, GET /common/countries/{country_iso_code}/states, and GET /common/countries/{country_iso_code}/pincodes (with query pincode=...&limit=1) to potentially provide dropdowns or validate inputs for Country, State, and City based on Pincode.

  • Update the cart with the collected address details using POST /carts/{id}/address:

    {
      "billing_address": { /* CustomerAddress object */ },
      "shipping_address": { /* CustomerAddress object */ }
    }
    

• Response: The POST /carts/{id}/address call returns the updated Cart object, which will now include potentially recalculated shipping_amount_including_tax and grand_total based on the destination. Re-render the cart summary if these values changed.

​

Step 3: (Optional) Validate Pincode Serviceability

Before allowing the user to proceed to payment, verify if delivery is possible to their chosen shipping pincode. This will only work if you have enabled an integration with a shipping provider that provides this service.

• GET /shipment/pincode-serviceability/{pincode}
• Path Parameter: pincode (from the shipping address).
• Response:
  • 200 OK with success: true: Delivery is available.
  • 4xx Error (e.g., 404 or specific error code if defined): Delivery is not available. Display an appropriate message to the user, preventing them from proceeding with this address.

​

Step 4: (Optional) Final Discounts/Credits

Provide options for the user to apply any last-minute coupons, loyalty points (logged-in only), or credit balance (logged-in only) using the respective POST /carts/{id}/... endpoints described in the Carts module documentation. Remember to handle potential errors (e.g., coupon requires login). Update the cart summary after each successful application.

​

Step 5: Create Order & Initiate Payment

This is the core transition from cart to order.

• POST /orders

• Authentication: Bearer Token

• Request Body:

  • cart_id: Required. The ID of the finalized cart.
  • payment_gateway: Required. "JUSPAY" or "PAYU". (Juspay recommended).
  • payment_gateway_params: Required. An object containing parameters specific to the chosen gateway.

  Example for Juspay (Hyper-Checkout - Recommended):

  {
    "cart_id": "YOUR_CART_ID",
    "payment_gateway": "JUSPAY",
    "payment_gateway_params": {
      "payment_gateway": "JUSPAY", // Discriminator field
      "action": "paymentPage",
      "integration_type": "hyper-checkout",
      "return_url": "<https://yourstore.com/checkout/payment-return>", // **Your** callback URL
      "gateway_reference_id": "OPTIONAL_PG_ID_IF_NEEDED" // Optional: Force specific PG in Juspay
    }
  }
  
  

  Example for PayU (Requires more setup):

  {
    "cart_id": "YOUR_CART_ID",
    "payment_gateway": "PAYU",
    "payment_gateway_params": {
      "payment_gateway": "PAYU", // Discriminator field
      "furl": "<https://yourstore.com/checkout/payment-failed>", // Your failure URL
      "surl": "<https://yourstore.com/checkout/payment-success>" // Your success URL (PayU uses different URLs)
      // Note: PayU often requires hashing done separately or specific client-side actions.
    }
  }
  
  

  (Advanced Use Cases): For Juspay Express Checkout or other complex integrations, consult the specific JuspayPaymentGatewayParams and PayuPaymentGatewayParams schemas and potentially use helper endpoints like POST /payments/juspay/create-order or POST /payments/generate-hash (PayU) before this step if required by your chosen integration pattern. Hyper-Checkout simplifies this significantly.

• Response (Success - 200 OK):

  • message, success
  • content:
    • order: The newly created OrderDetail object (initial status likely ‘draft’ or similar, payment_status: 'pending'). Contains the order_number.
    • payment_required: Boolean (usually true).
    • payment_info: An object containing instructions for the payment gateway. The structure depends on the chosen gateway (PayuPaymentInfo or JuspayPaymentInfo).

  Example payment_info for Juspay Hyper-Checkout:

  // ... within response content
  "payment_info": {
      "payment_gateway": "JUSPAY",
      "id": "...", // Juspay Payment Session ID
      "status": "NEW",
      "order_id": "...", // Juspay Order ID
      "payment_links": {
          "web": "<https://api.juspay.in/>...", // **URL to redirect the user to**
          "mobile": "...",
          "iframe": "..."
      },
      "sdk_payload": { /* Payload if using Juspay Mobile SDKs */ }
  }
  
  

  Example payment_info for PayU:

   // ... within response content
  "payment_info": {
      "payment_gateway": "PAYU",
      "key": "YOUR_PAYU_KEY",
      "txnid": "CE_GENERATED_TXN_ID",
      "amount": 100.00,
      "productinfo": "Order Description",
      "firstname": "Test",
      "email": "[email protected]",
      "phone": "9999999999",
      "surl": "<https://yourstore.com/checkout/payment-success>",
      "furl": "<https://yourstore.com/checkout/payment-failed>",
      "hash": "CALCULATED_PAYU_HASH"
      // ... other PayU specific fields
      // This data needs to be submitted to PayU via form post typically.
  }
  
  

​

Step 6: Process Payment

Based on the payment_info received:

• Juspay Hyper-Checkout: Redirect the user’s browser to the payment_info.payment_links.web URL. Juspay handles the payment method selection and processing.
• PayU: Typically requires submitting the fields from payment_info as a form POST to the PayU payment URL.
• Other Integrations (Juspay Express, SDKs): Follow the specific integration guide for the chosen method, using data from payment_info (e.g., sdk_payload for mobile SDKs).

The user interacts with the payment gateway interface to complete the payment.

​

Step 7: Handle Payment Callback/Redirect

Once the user completes (or cancels) the payment on the gateway’s page/interface, the gateway redirects them back to the return_url (for Juspay Hyper-Checkout) or surl/furl (for PayU) that you provided during order creation.

• This callback URL is on your storefront application.
• The URL might contain query parameters added by the gateway (e.g., transaction status, IDs), but DO NOT rely solely on these parameters to determine the final order status. They are informational and can sometimes be unreliable or manipulated.
• You must verify the definitive status with the Commerce Engine API.

​

Step 8: Verify Payment Status

On your callback/return page (return_url), the crucial step is to poll the Commerce Engine API to get the authoritative payment status for the order.

• Endpoint: GET /orders/{order_number}/payment-status

• Authentication: Bearer Token

• Path Parameter: order_number (obtained in Step 5 response).

• Polling Logic:

  1. Make the first call immediately when the user lands on the return_url.
  2. Check the content.status in the response.
  3. If status is success: Payment is confirmed. Proceed to Step 9 (Confirmation).
  4. If status is failed: Payment failed. Check content.is_retry_available. Proceed to Step 9 (Failure/Retry).
  5. If status is pending or partially_paid: The payment outcome is not yet final. Wait for a short interval (e.g., 5 seconds) and repeat the API call (poll again). Continue polling until the status becomes success or failed, or until a reasonable timeout (e.g., 1-2 minutes) is reached.

• Response (200 OK):

  {
    "message": "Payment status retrieved.",
    "success": true,
    "content": {
      "status": "success", // "pending", "failed", "partially_paid"
      "amount_paid": 100.00,
      "amount_unpaid": 0.00,
      "is_retry_available": false // boolean
    }
  }
  

Why Poll? Payment gateway notifications can be delayed or asynchronous. Polling GET /orders/{order_number}/payment-status ensures you get the confirmed status directly from Commerce Engine, which manages gateway webhooks and status updates reliably on the backend.

​

Step 9: Display Confirmation / Failure / Retry

Based on the final status obtained from polling:

• If status == success:
  • Display an Order Confirmation page showing order details (you can fetch full details again using GET /orders/{order_number}).
  • Thank the customer!
• If status == failed:
  • Check is_retry_available:
    • If true: Display a “Payment Failed” message and offer a “Retry Payment” button.
    • If false: Display an “Order Failed” message, explaining that payment could not be processed and potentially advising the customer to try again later or contact support. Do not offer an immediate retry.
• If Polling Times Out (Status remains pending): Display a message indicating the payment is still processing and advise the customer to check their order history later or contact support. Avoid confirming the order prematurely.

​

Handling Payment Retries

If payment failed but is_retry_available was true:

1. When the user clicks “Retry Payment”:

2. Call POST /orders/{order_number}/retry-payment.

3. Authentication: Bearer Token

4. Path Parameter: order_number.

5. Request Body: Similar to POST /orders, requires payment_gateway_params to potentially re-initiate the gateway flow (e.g., providing return_url again for Juspay).

    {
      "payment_gateway_params": {
        "payment_gateway": "JUSPAY", // Or PAYU
        "action": "paymentPage",
        "integration_type": "hyper-checkout",
        "return_url": "<https://yourstore.com/checkout/payment-return>",
        // ... other params if needed
      }
    }
   
   

6. Response: Similar to POST /orders, provides new payment_info (e.g., a new Juspay payment_links.web URL).

7. Redirect the user to the new payment URL (Step 6).

8. The process continues from Step 7 (Handling Callback) and Step 8 (Verify Payment Status).

Checkout Flow Diagram (Simplified - Juspay Hyper-Checkout):