Checkout

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.

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:

    Update Cart with Saved Address IDs

    {
      "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:

    Update Cart with New Address Objects

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

Before allowing the user to proceed to payment, verify if delivery is possible to their chosen shipping pincode.

• 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.

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.

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):

  Create Order Request (Juspay Hyper-Checkout)

  {
    "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):

  Create Order Request (PayU)

  {
    "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:

  Create Order Response (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:

  Create Order Response (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.
  }
  

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.

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).

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):

  Payment Status Response

  {
    "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
    }
  }
  

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. See “Handling Payment Retries” below.
    • 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 Retry Request Body (Juspay Example)

    {
      "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).