Checkout

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

• 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

    Copy

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

    Copy

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

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

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

  Copy

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

  Copy

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

  Copy

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

  Copy

   // ... 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": "test@example.com",
      "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.
  }
  

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

• This callback URL is on your storefront application.
• The URL might contain query parameters added by the gateway (e.g., transaction status, IDs).

• 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

  Copy

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

• 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

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)

   Copy

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