Checkout Session

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: ~~2025-10-02~~2026-05-23
Version: ~~v1.~~v2.0

Base URL: https://apinexgate.glueauth.com/api/v1/

Short Description: The Checkout Session API manages the complete checkout process for both e-commerce and event transactions. It handles ~~creating~~session ~~checkout~~creation ~~sessions~~(with ~~from~~upfront ~~cart~~wallet orbalance ~~direct~~validation), ~~purchase,~~inventory ~~managing~~holds, payment ~~intents,~~ processing ~~payments~~via ~~through multiple payment methods (~~Wallet, ~~Cash on Delivery, Cards, Mobile Money),~~Cash, and ~~supports~~Free ~~advanced features like~~flows, group ~~purchasing~~purchasing, and installment payments. Each session maintains state, inventory holds, and payment attempt tracking with automatic expiration handling.

Hints:

Wallet balance is validated at session creation time — if insufficient, no session is created and a rich balance response is returned so the frontend can guide the user to top up
All checkout sessions expire after 15 minutes by default
Inventory is automatically held during active sessions and released upon expiration or cancellation
Maximum 5 payment retry attempts allowed per session
Group purchase sessions require WALLET payment method only
Sessions in PAYMENT_PROCESSING status cannot be modified
Installment payment ~~type~~only ischarges ~~planned~~the ~~for~~down ~~future~~payment ~~release~~at ~~(placeholder~~checkout; ~~only)~~monthly payments are handled by the scheduler
All monetary values are in TZS (Tanzanian Shillings)
Use ISO 8601 format for all datetime fields
Sessions can only be updated when in PENDING_PAYMENT or PAYMENT_FAILED status

Full Checkout Flow Diagram

CLIENT                          BACKEND                         SYSTEMS
  |                               |                               |
  |  POST /checkout-sessions      |                               |
  |------------------------------>|                               |
  |                               |-- Validate request            |
  |                               |-- Calculate pricing           |
  |                               |                               |
  |                               |-- assertSufficientBalance()   |
  |                               |        |                      |
  |                               |        |-- GET wallet balance -|-> Ledger
  |                               |        |                      |
  |                               |   .......................      |
  |                               |   . BALANCE INSUFFICIENT .    |
  |                               |   .......................      |
  |    422 + rich balance data    |        |                      |
  |<------------------------------|<-------'                      |
  |  {                            |                               |
  |    walletBalance: 5000,       |                               |
  |    sessionTotal: 12000,       |                               |
  |    shortfall: 7000,           |                               |
  |    recommendedTopUp: 7000     |                               |
  |  }                            |                               |
  |                               |                               |
  |                               |   .......................      |
  |                               |   .  BALANCE SUFFICIENT  .    |
  |                               |   .......................      |
  |                               |        |                      |
  |                               |-- Hold inventory ------------>|-> Inventory
  |                               |-- Save session                |
  |                               |-- Schedule expiry job ------->|-> JobRunr
  |                               |                               |
  |    201 + session data         |                               |
  |<------------------------------|                               |
  |  { sessionId, status:         |                               |
  |    PENDING_PAYMENT, ... }     |                               |
  |                               |                               |
  |  ...15 min window...          |                               |
  |                               |                               |
  |  POST /{sessionId}/payment    |                               |
  |------------------------------>|                               |
  |                               |-- Validate status             |
  |                               |-- Check expiry                |
  |                               |                               |
  |                               |   .......................      |
  |                               |   .    FREE checkout     .    |
  |                               |   .......................      |
  |                               |        |                      |
  |                               |-- Create booking/order        |
  |                               |-- Track free transaction      |
  |    200 SUCCESS                |                               |
  |<------------------------------|                               |
  |                               |                               |
  |                               |   .......................      |
  |                               |   .    CASH checkout     .    |
  |                               |   .......................      |
  |                               |        |                      |
  |                               |-- Create booking/order        |
  |                               |-- Track cash transaction      |
  |    200 SUCCESS                |                               |
  |<------------------------------|                               |
  |                               |                               |
  |                               |   .......................      |
  |                               |   .   WALLET checkout    .    |
  |                               |   .......................      |
  |                               |        |                      |
  |                               |-- Set PAYMENT_PROCESSING      |
  |                               |-- holdMoney() --------------->|-> Escrow
  |                               |                               |
  |                               |   .......................      |
  |                               |   .     SUCCESS          .    |
  |                               |   .......................      |
  |                               |        |                      |
  |                               |-- Set PAYMENT_COMPLETED       |
  |                               |-- Create order/booking        |
  |                               |-- Commit inventory hold ----->|-> Inventory
  |                               |-- Publish payment event ----->|-> Notifications
  |    200 SUCCESS                |                               |
  |<------------------------------|                               |
  |  { orderId, escrowId,         |                               |
  |    amountPaid, ... }          |                               |
  |                               |                               |
  |                               |   .......................      |
  |                               |   .     FAILED           .    |
  |                               |   .......................      |
  |                               |        |                      |
  |                               |-- recordFailedAttempt()       |
  |                               |-- Release reservation         |
  |                               |   (events only)               |
  |    200 FAILED                 |                               |
  |<------------------------------|                               |
  |  { success: false,            |                               |
  |    canRetry: true/false }     |                               |
  |                               |                               |
  |  POST /{sessionId}/retry      |                               |
  |------------------------------>|                               |
  |                               |-- Check status = FAILED       |
  |                               |-- Check attempts < 5          |
  |                               |-- Re-validate inventory       |
  |                               |-- Check wallet balance        |
  |                               |-- Re-hold inventory           |
  |                               |-- Reset to PENDING_PAYMENT    |
  |                               |-- processPayment() ...        |
  |                               |   (same wallet flow above)    |

Session Type Routing

POST /checkout-sessions
  sessionType?
  .
  ├─ REGULAR_DIRECTLY ──> validate 1 item ──> balance check ──> hold inventory ──> session
  |
  ├─ REGULAR_CART ──────> validate cart ───> balance check ──> hold inventory ──> session
  |
  ├─ GROUP_PURCHASE ────> validate group ──> balance check ──> session (no hold, group-level)
  |
  └─ INSTALLMENT ───────> calculate down payment ──> balance check ──> hold inventory ──> session


POST /e-events/checkout
  ticketPricingType?
  .
  ├─ PAID ──> balance check ──> create payment intent ──> reserve ticket ──> session
  |
  └─ FREE ──> (no balance check) ──> reserve ticket ──> session

Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-10-02T10:30:45",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-10-02T10:30:45",
  "data": "Error description"
}

Insufficient Balance Error Structure (422)

This is a special structured error returned when wallet balance is insufficient at session creation time. The data field contains rich balance details so the frontend can guide the user to top up.

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Insufficient wallet balance to complete checkout",
  "action_time": "2025-10-02T10:30:45",
  "data": {
    "walletBalance": 5000.00,
    "sessionTotal": 12000.00,
    "shortfall": 7000.00,
    "hasSufficientBalance": false,
    "recommendedTopUp": 7000.00,
    "pspMinimum": 500.00,
    "currency": "TZS"
  }
}

Field	Description
`walletBalance`	Current wallet balance of the user
`sessionTotal`	Total amount required for this checkout
`shortfall`	How much is missing (`sessionTotal - walletBalance`)
`hasSufficientBalance`	Always `false` when this error is returned
`recommendedTopUp`	Suggested top-up amount (at least `shortfall`, rounded up to PSP minimum)
`pspMinimum`	Minimum top-up amount accepted by the payment provider
`currency`	Always `TZS`

Standard Response Fields

Field	Type	Description
`success`	boolean	Always `true` for successful operations, `false` for errors
`httpStatus`	string	HTTP status name (OK, CREATED, BAD_REQUEST, NOT_FOUND, etc.)
`message`	string	Human-readable message describing the operation result
`action_time`	string	ISO 8601 timestamp of when the response was generated
`data`	object/string	Response payload for success, error details for failures

HTTP Method Badge Standards

For better visual clarity, all endpoints use colored badges for HTTP methods with the following standard colors:

GET - GET - Green (Safe, read-only operations)
POST - POST - Blue (Create new resources)
PATCH - PATCH - Orange (Partial updates)
DELETE - DELETE - Red (Remove resources)

Endpoints

1. Create Checkout Session

Purpose: Creates a new checkout session for processing a purchase. Wallet balance is validated upfront — if insufficient, no session is created and the caller receives rich balance data to guide the user. Supports multiple checkout types: direct product purchase, cart checkout, group purchasing, and installment ~~payments (future).~~payments.

Endpoint: POST {base_url}/checkout-sessions

Access Level: 🔒 Protected (Requires Authentication)

Authentication: Bearer Token required in Authorization header

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authenticated user
Content-Type	string	Yes	Must be `application/json`

Request JSON Sample:

{
  "sessionType": "REGULAR_DIRECTLY",
  "items": [
    {
      "productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "quantity": 2
    }
  ],
  "shippingAddressId": "f1e2d3c4-b5a6-7890-cdef-123456789abc",
  "shippingMethodId": "standard-shipping",
  "metadata": {
    "couponCode": "SAVE20",
    "referralCode": "REF123",
    "notes": "Please handle with care"
  },
  "installmentPlanId": null,
  "groupInstanceId": null,
  "downPaymentPercent": 20,20
}

Request Body Parameters:

-~~PLACEHOLDERFORFUTURE~~

Parameter	Type	Required	Description	Validation
sessionType	string	Yes	Type of checkout session	enum: REGULAR_DIRECTLY, REGULAR_CART, GROUP_PURCHASE, INSTALLMENT
items	array	Conditional	Array of items to checkout. Required for REGULAR_DIRECTLY and GROUP_PURCHASE	For REGULAR_DIRECTLY: exactly 1 item. For GROUP_PURCHASE: exactly 1 item. Not used for REGULAR_CART
items[].productId	string (UUID)	Yes (if items provided)	Product identifier	Valid UUID format
items[].quantity	integer	Yes (if items provided)	Quantity to purchase	Min: 1, must not exceed product constraints
shippingAddressId	string (UUID)	Yes	User's shipping address identifier	Valid UUID format, must belong to authenticated user
shippingMethodId	string	Yes	Selected shipping method identifier	Must be valid shipping method
metadata	object	No	Additional metadata for the session	Key-value pairs for coupons, referrals, notes, etc.
installmentPlanId	string (UUID)	NoConditional	Installment plan identifier (~~for~~ INSTALLMENT type only)	Valid UUID format
downPaymentPercent	integer	Conditional	Down payment percentage (INSTALLMENT type only)	Must satisfy plan's min/max constraints
groupInstanceId	string (UUID)	No	Group instance to join (~~for~~ GROUP_PURCHASE type only)	Valid UUID format, group must be ~~joinable~~joinable. Null = create new group
groupName	string	Conditional	Name for new group (GROUP_PURCHASE, groupInstanceId null)	Must be unique per product

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK"CREATED",
  "message": "Checkout session created successfully",
  "action_time": "2025-10-02T14:30:45",
  "data": {
    "sessionId": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
    "sessionType": "REGULAR_DIRECTLY",
    "status": "PENDING_PAYMENT",
    "customerId": "u1s2e3r4-i5d6-7890-abcd-ef1234567890",
    "customerUserName": "john_doe",
    "items": [
      {
        "productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "productName": "Premium Wireless Headphones",
        "productSlug": "premium-wireless-headphones",
        "productImage": "https://cdn.nextgate.com/products/headphones-001.jpg",
        "quantity": 2,
        "unitPrice": 150000.00,
        "discountAmount": 20000.00,
        "subtotal": 300000.00,
        "tax": 0.00,
        "total": 280000.00,
        "shopId": "s1h2o3p4-i5d6-7890-abcd-ef1234567890",
        "shopName": "TechWorld Electronics",
        "shopLogo": "https://cdn.nextgate.com/shops/techworld-logo.jpg",
        "availableForCheckout": true,
        "availableQuantity": 50
      }
    ],
    "pricing": {
      "subtotal": 300000.00,
      "discount": 20000.00,
      "shippingCost": 5000.00,
      "tax": 0.00,
      "total": 285000.00,
      "currency": "TZS"
    },
    "shippingAddress": {
      "fullName": "John Doe",
      "addressLine1": "123 Main Street",
      "addressLine2": "Apartment 4B",
      "city": "Dar es Salaam",
      "state": "Dar es Salaam Region",
      "postalCode": "12345",
      "country": "Tanzania",
      "phone": "+255123456789"
    },
    "billingAddress": {
      "sameAsShipping": false,
      "fullName": "John Doe",
      "addressLine1": "456 Business Ave",
      "city": "Dar es Salaam",
      "state": "Dar es Salaam Region",
      "postalCode": "12346",
      "country": "Tanzania"
    },
    "shippingMethod": {
      "id": "standard-shipping",
      "name": "Standard Shipping",
      "carrier": "DHL",
      "cost": 5000.00,
      "estimatedDays": "3-5 business days",
      "estimatedDelivery": "2025-10-07T14:30:45"
    },
    "paymentIntent": {
      "provider": "WALLET",
      "clientSecret": null,
      "paymentMethods": ["WALLET"],
      "status": "READY"
    },
    "paymentAttempts": [],
    "inventoryHeld": true,
    "inventoryHoldExpiresAt": "2025-10-02T14:45:45",
    "metadata": {
      "couponCode": "SAVE20",
      "referralCode": "REF123",
      "notes": "Please handle with care"
    },
    "expiresAt": "2025-10-02T14:45:45",
    "createdAt": "2025-10-02T14:30:45",
    "updatedAt": "2025-10-02T14:30:45",
    "completedAt": null,
    "createdOrderId": null,
    "cartId": null
  }
}

Success Response Fields:

Field	Description
sessionId	Unique identifier for the checkout session
sessionType	Type of checkout (REGULAR_DIRECTLY, REGULAR_CART, GROUP_PURCHASE, INSTALLMENT)
status	Current status of the session (~~PENDING_PAYMENT,~~always ~~PAYMENT_PROCESSING,~~PENDING_PAYMENT ~~PAYMENT_COMPLETED,~~on ~~PAYMENT_FAILED, EXPIRED, CANCELLED, COMPLETED)~~creation)
customerId	User ID who created the session
customerUserName	Username of the customer
items	Array of checkout items with product details, pricing, and availability
~~items[].productId~~	~~Product unique identifier~~
~~items[].productName~~	~~Product display name~~
~~items[].productSlug~~	~~URL-friendly product identifier~~
~~items[].productImage~~	~~Primary product image URL~~
~~items[].quantity~~	~~Quantity being purchased~~
~~items[].unitPrice~~	~~Price per unit in TZS~~
~~items[].discountAmount~~	~~Total discount applied to this item~~
~~items[].subtotal~~	~~Unit price × quantity~~
~~items[].tax~~	~~Tax amount for this item~~
~~items[].total~~	~~Final total for this item (subtotal + tax - discount)~~
~~items[].shopId~~	~~Shop identifier selling this product~~
~~items[].shopName~~	~~Shop display name~~
~~items[].shopLogo~~	~~Shop logo URL~~
~~items[].availableForCheckout~~	~~Whether product is currently available~~
~~items[].availableQuantity~~	~~Current stock quantity available~~
pricing	Summary of all pricing calculations
pricing.~~subtotal~~	~~Sum of all item subtotals~~
~~pricing.discount~~	~~Total discount applied~~
~~pricing.shippingCost~~	~~Shipping fee~~
~~pricing.tax~~	~~Total tax amount~~
~~pricing.~~total	Final amount to be ~~paid~~charged (~~subtotal~~what +was ~~shippingCost~~validated +against ~~tax~~wallet ~~- discount)~~balance)
pricing.currency	~~Currency~~Always ~~code (TZS)~~TZS
shippingAddress	Complete shipping address details
~~billingAddress~~	~~Billing address (may differ from shipping)~~
~~billingAddress.sameAsShipping~~	~~Whether billing address matches shipping address~~
shippingMethod	Selected shipping method details
~~shippingMethod.id~~	~~Shipping method identifier~~
~~shippingMethod.name~~	~~Display name of shipping method~~
~~shippingMethod.carrier~~	~~Carrier company name~~
~~shippingMethod.cost~~	~~Shipping fee in TZS~~
~~shippingMethod.estimatedDays~~	~~Estimated delivery timeframe~~
~~shippingMethod.estimatedDelivery~~	~~Estimated delivery datetime~~
paymentIntent	Payment processing details
~~paymentIntent.provider~~	~~Payment provider (WALLET, CASH_ON_DELIVERY, CREDIT_CARD, etc.)~~
~~paymentIntent.clientSecret~~	~~Client secret for payment processing (null for WALLET/COD)~~
~~paymentIntent.paymentMethods~~	~~List of available payment methods~~
~~paymentIntent.status~~	~~Payment intent status (READY, PENDING, etc.)~~
paymentAttempts	~~Array~~Empty ~~of payment attempts made~~array on ~~this session~~creation
inventoryHeld	Whether inventory is currently held (false for ~~this session~~GROUP_PURCHASE)
inventoryHoldExpiresAt	When the inventory hold will be released
~~metadata~~	~~Custom metadata provided during creation~~
expiresAt	When this checkout session expires
~~createdAt~~	~~Session creation timestamp~~
~~updatedAt~~	~~Last update timestamp~~
~~completedAt~~	~~Completion timestamp~~ (~~null~~15 ~~until~~minutes ~~completed)~~from creation)
createdOrderId	~~Order ID created after successful payment (~~null until ~~completed)~~payment succeeds
cartId	Cart ID if session was created from ~~cart~~cart, (null ~~for REGULAR_DIRECTLY)~~otherwise

Error ~~Response JSON Sample~~Responses:

Insufficient Wallet Balance (422) — includes rich top-up data:

{
  "success": false,
  "httpStatus": "BAD_REQUEST"UNPROCESSABLE_ENTITY",
  "message": "ValidationInsufficient failed"wallet balance to complete checkout",
  "action_time": "2025-10-02T14:30:45",
  "data": {
    "sessionType"walletBalance": 150000.00,
    "sessionTotal": 285000.00,
    "shortfall": 135000.00,
    "hasSufficientBalance": false,
    "recommendedTopUp": 135000.00,
    "pspMinimum": 500.00,
    "currency": "must not be null",
    "items": "Items are required for checkout",
    "shippingAddressId": "must not be null"TZS"
  }
}

~~Standard Error Types~~:

Application-Level Exceptions (400-499)

400 BAD_REQUEST~~: Invalid request data, validation errors, business rule violations~~

401 UNAUTHORIZED~~: Missing, invalid, or expired authentication token~~

403 FORBIDDEN~~: Insufficient permissions or verification required~~

404 NOT_FOUND~~: Product, payment method, shipping address, or other resource not found~~

422 UNPROCESSABLE_ENTITY~~: Validation errors with detailed field information~~

Server-Level Exceptions (500+)

500 INTERNAL_SERVER_ERROR~~: Unexpected server errors~~

~~Error Response Examples~~:

Bad Request - Invalid Session Type (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "REGULAR_DIRECTLY checkout supports only 1 item. Use REGULAR_CART for multiple items.",
  "action_time": "2025-10-02T14:30:45",
  "data": "REGULAR_DIRECTLY checkout supports only 1 item. Use REGULAR_CART for multiple items."
}

Bad Request - Insufficient Inventory (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Insufficient stock. Available: 3, Requested: 5",
  "action_time": "2025-10-02T14:30:45",
  "data": "Insufficient stock. Available: 3, Requested: 5"
}

~~Bad Request - Insufficient Wallet Balance (400):~~

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Insufficient wallet balance. Required: 285000 TZS, Available: 150000 TZS",
  "action_time": "2025-10-02T14:30:45",
  "data": "Insufficient wallet balance. Required: 285000 TZS, Available: 150000 TZS"
}

~~Unauthorized - Token Missing (401):~~

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Authentication token is required",
  "action_time": "2025-10-02T14:30:45",
  "data": "Authentication token is required"
}

~~Not Found - Product Not Found (404):~~

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Product not found",
  "action_time": "2025-10-02T14:30:45",
  "data": "Product not found"
}

~~Not Found - Payment Method Not Found (404):~~

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Payment method not found or does not belong to you",
  "action_time": "2025-10-02T14:30:45",
  "data": "Payment method not found or does not belong to you"
}

Validation Error (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-10-02T14:30:45",
  "data": {
    "sessionType": "must not be null",
    "items[0].quantity": "must be greater than or equal to 1",
    "shippingAddressId": "must not be null"
  }
}

Not Found - Product Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Product not found",
  "action_time": "2025-10-02T14:30:45",
  "data": "Product not found"
}

Unauthorized (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Authentication token is required",
  "action_time": "2025-10-02T14:30:45",
  "data": "Authentication token is required"
}

2. Get Checkout Session by ID

Purpose: Retrieves detailed information about a specific checkout session by its ID. Only the session owner can access their session.

Endpoint: GET {base_url}/checkout-sessions/{sessionId}

Access Level: 🔒 Protected (Requires Authentication and Ownership)

Authentication: Bearer Token required in Authorization header

~~Request Headers~~:

~~Header~~	~~Type~~	~~Required~~	~~Description~~
~~Authorization~~	~~string~~	~~Yes~~	~~Bearer token for authenticated user~~

Path Parameters:

Parameter	Type	Required	Description	Validation
sessionId	string (UUID)	Yes	Unique identifier of the checkout session	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Checkout session retrieved successfully",
  "action_time": "2025-10-02T14:35:45",
  "data": {
    "sessionId": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
    "sessionType": "REGULAR_DIRECTLY",
    "status": "PENDING_PAYMENT",
    "customerId": "u1s2e3r4-i5d6-7890-abcd-ef1234567890",
    "customerUserName": "john_doe",
    "items": [
      {
        "productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "productName": "Premium Wireless Headphones",
        "productSlug": "premium-wireless-headphones",
        "productImage": "https://cdn.nextgate.com/products/headphones-001.jpg",
        "quantity": 2,
        "unitPrice": 150000.00,
        "discountAmount": 20000.00,
        "subtotal": 300000.00,
        "tax": 0.00,
        "total": 280000.00,
        "shopId": "s1h2o3p4-i5d6-7890-abcd-ef1234567890",
        "shopName": "TechWorld Electronics",
        "shopLogo": "https://cdn.nextgate.com/shops/techworld-logo.jpg",
        "availableForCheckout": true,
        "availableQuantity": 50
      }
    ],
    "pricing": {
      "subtotal": 300000.00,
      "discount": 20000.00,
      "shippingCost": 5000.00,
      "tax": 0.00,
      "total": 285000.00,
      "currency": "TZS"
    },
    "shippingAddress": {
      "fullName": "John Doe",
      "addressLine1": "123 Main Street",
      "addressLine2": "Apartment 4B",
      "city": "Dar es Salaam",
      "state": "Dar es Salaam Region",
      "postalCode": "12345",
      "country": "Tanzania",
      "phone": "+255123456789"
    },
    "billingAddress": {
      "sameAsShipping": false,
      "fullName": "John Doe",
      "addressLine1": "456 Business Ave",
      "city": "Dar es Salaam",
      "state": "Dar es Salaam Region",
      "postalCode": "12346",
      "country": "Tanzania"
    },
    "shippingMethod": {
      "id": "standard-shipping",
      "name": "Standard Shipping",
      "carrier": "DHL",
      "cost": 5000.00,
      "estimatedDays": "3-5 business days",
      "estimatedDelivery": "2025-10-07T14:30:45"
    },
    "paymentIntent": {
      "provider": "WALLET",
      "clientSecret": null,
      "paymentMethods": ["WALLET"],
      "status": "READY"
    },
    "paymentAttempts": [],
    "inventoryHeld": true,
    "inventoryHoldExpiresAt": "2025-10-02T14:45:45",
    "metadata": { "couponCode": "SAVE20" },
    "expiresAt": "2025-10-02T14:45:45",
    "createdAt": "2025-10-02T14:30:45",
    "updatedAt": "2025-10-02T14:30:45",
    "completedAt": null,
    "createdOrderId": null,
    "cartId": null
  }
}

~~Success Response Fields~~:

~~Field~~	~~Description~~
~~sessionId~~	~~Unique identifier for the checkout session~~
~~sessionType~~	~~Type of checkout session~~
~~status~~	~~Current status of the session~~
~~customerId~~	~~User ID who owns the session~~
~~customerUserName~~	~~Username of the customer~~
~~items~~	~~Array of checkout items (see Create Checkout Session for details)~~
~~pricing~~	~~Pricing summary (see Create Checkout Session for details)~~
~~shippingAddress~~	~~Shipping address details~~
~~billingAddress~~	~~Billing address details~~
~~shippingMethod~~	~~Shipping method information~~
~~paymentIntent~~	~~Payment intent details~~
~~paymentAttempts~~	~~Array of all payment attempts made~~
~~inventoryHeld~~	~~Whether inventory is currently held~~
~~inventoryHoldExpiresAt~~	~~When inventory hold expires~~
~~metadata~~	~~Custom metadata~~
~~expiresAt~~	~~Session expiration datetime~~
~~createdAt~~	~~Session creation timestamp~~
~~updatedAt~~	~~Last update timestamp~~
~~completedAt~~	~~Completion timestamp (null if not completed)~~
~~createdOrderId~~	~~Order ID after successful payment (null if not completed)~~
~~cartId~~	~~Cart ID if created from cart~~

Error ~~Response JSON Sample~~:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Checkout session not found or you don't have permission to access it",
  "action_time": "2025-10-02T14:35:45",
  "data": "Checkout session not found or you don't have permission to access it"
}

~~Error Response Examples~~Responses:

Not Found - Session Not Found or No Permission (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Checkout session not found or you don't have permission to access it",
  "action_time": "2025-10-02T14:35:45",
  "data": "Checkout session not found or you don't have permission to access it"
}

~~Unauthorized (401):~~

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Authentication token is required",
  "action_time": "2025-10-02T14:35:45",
  "data": "Authentication token is required"
}

3. Get My Checkout Sessions

Purpose: Retrieves all checkout sessions belonging to the authenticated user, ordered by creation date (newest first).

Endpoint: GET {base_url}/checkout-sessions

Access Level: 🔒 Protected (Requires Authentication)

~~Authentication~~~~: Bearer Token required in Authorization header~~

~~Request Headers~~:

~~Header~~	~~Type~~	~~Required~~	~~Description~~
~~Authorization~~	~~string~~	~~Yes~~	~~Bearer token for authenticated user~~

~~Success Response JSON Sample~~:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Checkout sessions retrieved successfully",
  "action_time": "2025-10-02T14:40:45",
  "data": [
    {
      "sessionId": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
      "sessionType": "REGULAR_DIRECTLY",
      "status": "PENDING_PAYMENT",
      "itemCount": 1,
      "totalAmount": 285000.00,
      "currency": "TZS",
      "expiresAt": "2025-10-02T14:45:45",
      "createdAt": "2025-10-02T14:30:45",
      "isExpired": false,
      "canRetryPayment": false,
      "itemPreviews": [
        {
          "productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "productName": "Premium Wireless Headphones",
          "productImage": "https://cdn.nextgate.com/products/headphones-001.jpg",
          "quantity": 2,
          "unitPrice": 150000.00,
          "total": 280000.00,
          "shopName": "TechWorld Electronics"
        }
      ]
    },
    {
      "sessionId": "d2e3f4a5-b6c7-8901-def0-234567890abc",
      "sessionType": "REGULAR_CART",
      "status": "COMPLETED",
      "itemCount": 3,
      "totalAmount": 500000.00,
      "currency": "TZS",
      "expiresAt": "2025-10-01T10:15:30",
      "createdAt": "2025-10-01T10:00:30",
      "isExpired": false,
      "canRetryPayment": false,
      "itemPreviews": [
        {
          "productId": "p1r2o3d4-u5c6-7890-abcd-ef1234567890",
          "productName": "Smart Watch Series 5",
          "productImage": "https://cdn.nextgate.com/products/watch-005.jpg",
          "quantity": 1,
          "unitPrice": 350000.00,
          "total": 350000.00,
          "shopName": "Gadget Hub"
        },
        {
          "productId": "p2r3o4d5-u6c7-8901-bcde-f12345678901",
          "productName": "Wireless Mouse",
          "productImage": "https://cdn.nextgate.com/products/mouse-003.jpg",
          "quantity": 2,
          "unitPrice": 45000.00,
          "total": 90000.00,
          "shopName": "TechWorld Electronics"
        }
      ]
    },
    {
      "sessionId": "e3f4a5b6-c7d8-9012-ef01-345678901bcd",
      "sessionType": "PAYMENT_FAILED",
      "status": "PAYMENT_FAILED",
      "itemCount": 1,
      "totalAmount": 120000.00,
      "currency": "TZS",
      "expiresAt": "2025-10-02T15:00:00",
      "createdAt": "2025-10-02T14:45:00",
      "isExpired": false,
      "canRetryPayment": true,
      "itemPreviews": [
        {
          "productId": "p3r4o5d6-u7c8-9012-cdef-234567890123",
          "productName": "USB-C Cable 2m",
          "productImage": "https://cdn.nextgate.com/products/cable-002.jpg",
          "quantity": 5,
          "unitPrice": 15000.00,
          "total": 75000.00,
          "shopName": "Accessories World"
        }
      ]
    }
  ]
}

Success Response Fields:

Field	Description
sessionId	Unique identifier for the checkout session
sessionType	Type of checkout session
status	Current status of the session
itemCount	Number of items in the checkout
totalAmount	Total amount to be paid in TZS
currency	Currency code (TZS)
expiresAt	When this session expires
createdAt	When this session was created
isExpired	Whether the session has expired
canRetryPayment	~~Whether payment can be retried (~~true only if status is PAYMENT_FAILED and not ~~expired)~~expired and attempts < 5
itemPreviews	Array of preview information for items ~~in checkout~~
~~itemPreviews[].productId~~	~~Product unique identifier~~
~~itemPreviews[].productName~~	~~Product name~~
~~itemPreviews[].productImage~~	~~Product image URL~~
~~itemPreviews[].quantity~~	~~Quantity being purchased~~
~~itemPreviews[].unitPrice~~	~~Price per unit~~
~~itemPreviews[].total~~	~~Total for this item~~
~~itemPreviews[].shopName~~	~~Shop selling this product~~

~~Error Response JSON Sample~~:

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Authentication token is required",
  "action_time": "2025-10-02T14:40:45",
  "data": "Authentication token is required"
}

~~Error Response Examples~~:

~~Unauthorized (401):~~

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Authentication token is required",
  "action_time": "2025-10-02T14:40:45",
  "data": "Authentication token is required"
}

4. Get My Active Checkout Sessions

Purpose: Retrieves only active checkout sessions (PENDING_PAYMENT or PAYMENT_FAILED status) that haven't expired yet, ordered by creation date (newest first).

Endpoint: GET {base_url}/checkout-sessions/active

Access Level: 🔒 Protected (Requires Authentication)

~~Authentication~~Notes: ~~Bearer Token required in Authorization header~~

~~Request Headers~~:

~~Header~~	~~Type~~	~~Required~~	~~Description~~
~~Authorization~~	~~string~~	~~Yes~~	~~Bearer token for authenticated user~~

~~Success~~ Response ~~JSON~~structure ~~Sample~~:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Active checkout sessions retrieved successfully",
  "action_time": "2025-10-02T14:42:45",
  "data": [
    {
      "sessionId": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
      "sessionType": "REGULAR_DIRECTLY",
      "status": "PENDING_PAYMENT",
      "itemCount": 1,
      "totalAmount": 285000.00,
      "currency": "TZS",
      "expiresAt": "2025-10-02T14:45:45",
      "createdAt": "2025-10-02T14:30:45",
      "isExpired": false,
      "canRetryPayment": false,
      "itemPreviews": [
        {
          "productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "productName": "Premium Wireless Headphones",
          "productImage": "https://cdn.nextgate.com/products/headphones-001.jpg",
          "quantity": 2,
          "unitPrice": 150000.00,
          "total": 280000.00,
          "shopName": "TechWorld Electronics"
        }
      ]
    },
    {
      "sessionId": "e3f4a5b6-c7d8-9012-ef01-345678901bcd",
      "sessionType": "GROUP_PURCHASE",
      "status": "PAYMENT_FAILED",
      "itemCount": 1,
      "totalAmount": 120000.00,
      "currency": "TZS",
      "expiresAt": "2025-10-02T15:00:00",
      "createdAt": "2025-10-02T14:45:00",
      "isExpired": false,
      "canRetryPayment": true,
      "itemPreviews": [
        {
          "productId": "p3r4o5d6-u7c8-9012-cdef-234567890123",
          "productName": "USB-C Cable 2m",
          "productImage": "https://cdn.nextgate.com/products/cable-002.jpg",
          "quantity": 5,
          "unitPrice": 15000.00,
          "total": 75000.00,
          "shopName": "Accessories World"
        }
      ]
    }
  ]
}

~~Success Response Fields~~:

filteredtoactive

~~Field~~	~~Description~~
~~sessionId~~	~~Unique identifier for~~is the ~~checkout~~same ~~session~~
~~sessionType~~	~~Type of checkout session~~
~~status~~	~~Current status (PENDING_PAYMENT or PAYMENT_FAILED only)~~
~~itemCount~~	~~Number of items in the checkout~~
~~totalAmount~~	~~Total amount to be paid in TZS~~
~~currency~~	~~Currency code (TZS)~~
~~expiresAt~~	~~When this session expires~~
~~createdAt~~	~~When this session was created~~
~~isExpired~~	~~Always false for active sessions~~
~~canRetryPayment~~	~~Whether payment can be retried~~
~~itemPreviews~~	~~Array of preview information for items (see~~as Get My Checkout Sessions ~~for~~but ~~details)~~

sessions

~~Error~~only. ~~Response JSON Sample~~:

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Authentication tokenisExpired is required",always "action_time":false "2025-10-02T14:42:45",in "data":this "Authentication token is required"
}

~~Error Response Examples~~:response.

~~Unauthorized (401):~~

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Authentication token is required",
  "action_time": "2025-10-02T14:42:45",
  "data": "Authentication token is required"
}

5. Update Checkout Session

Purpose: Updates an existing checkout session. Can modify shipping address, shipping ~~method, payment~~ method, or metadata. Only sessions in PENDING_PAYMENT or PAYMENT_FAILED status can be updated.

Endpoint: PATCH {base_url}/checkout-sessions/{sessionId}

Access Level: 🔒 Protected (Requires Authentication and Ownership)

~~Authentication~~~~: Bearer Token required in Authorization header~~

~~Request Headers~~:

~~Header~~	~~Type~~	~~Required~~	~~Description~~
~~Authorization~~	~~string~~	~~Yes~~	~~Bearer token for authenticated user~~
~~Content-Type~~	~~string~~	~~Yes~~	~~Must be~~ `application/json`

Path Parameters:

Parameter	Type	Required	Description	~~Validation~~
sessionId	string (UUID)	Yes	Unique identifier of the checkout session	~~Valid UUID format~~

~~Request JSON Sample~~:

{
  "shippingAddressId": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "shippingMethodId": "express-shipping",
  "paymentMethodId": "p9a8y7m6-e5n4-3210-tdef-ba9876543210",
  "metadata": {
    "giftWrapping": true,
    "giftMessage": "Happy Birthday!"
  }
}

Request Body Parameters:

(triggers

Parameter	Type	Required	Description	~~Validation~~
shippingAddressId	string (UUID)	No	New shipping address identifier	~~Valid UUID format, must belong to user~~
shippingMethodId	string	No	New shipping method ~~identifier~~	~~Must~~pricing ~~be valid shipping method~~
~~paymentMethodId~~	~~string (UUID)~~	No	~~New payment method identifier~~	~~Valid UUID format, must belong to user~~recalculation)
metadata	object	No	~~Additional or updated metadata~~	Key-value pairs, merged with existing metadata

~~Success Response JSON Sample~~:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Checkout session updated successfully",
  "action_time": "2025-10-02T14:50:45",
  "data": {
    "sessionId": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
    "sessionType": "REGULAR_DIRECTLY",
    "status": "PENDING_PAYMENT",
    "customerId": "u1s2e3r4-i5d6-7890-abcd-ef1234567890",
    "customerUserName": "john_doe",
    "items": [
      {
        "productId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "productName": "Premium Wireless Headphones",
        "productSlug": "premium-wireless-headphones",
        "productImage": "https://cdn.nextgate.com/products/headphones-001.jpg",
        "quantity": 2,
        "unitPrice": 150000.00,
        "discountAmount": 20000.00,
        "subtotal": 300000.00,
        "tax": 0.00,
        "total": 280000.00,
        "shopId": "s1h2o3p4-i5d6-7890-abcd-ef1234567890",
        "shopName": "TechWorld Electronics",
        "shopLogo": "https://cdn.nextgate.com/shops/techworld-logo.jpg",
        "availableForCheckout": true,
        "availableQuantity": 50
      }
    ],
    "pricing": {
      "subtotal": 300000.00,
      "discount": 20000.00,
      "shippingCost": 8000.00,
      "tax": 0.00,
      "total": 288000.00,
      "currency": "TZS"
    },
    "shippingAddress": {
      "fullName": "John Doe",
      "addressLine1": "789 New Address Street",
      "addressLine2": null,
      "city": "Dar es Salaam",
      "state": "Dar es Salaam Region",
      "postalCode": "12347",
      "country": "Tanzania",
      "phone": "+255987654321"
    },
    "billingAddress": {
      "sameAsShipping": false,
      "fullName": "John Doe",
      "addressLine1": "321 Payment Ave",
      "city": "Dar es Salaam",
      "state": "Dar es Salaam Region",
      "postalCode": "12348",
      "country": "Tanzania"
    },
    "shippingMethod": {
      "id": "express-shipping",
      "name": "Express Shipping",
      "carrier": "DHL",
      "cost": 8000.00,
      "estimatedDays": "1-2 business days",
      "estimatedDelivery": "2025-10-04T14:50:45"
    },
    "paymentIntent": {
      "provider": "CREDIT_CARD",
      "clientSecret": "pi_1234567890abcdef",
      "paymentMethods": ["CREDIT_CARD", "DEBIT_CARD"],
      "status": "READY"
    },
    "paymentAttempts": [],
    "inventoryHeld": true,
    "inventoryHoldExpiresAt": "2025-10-02T15:05:45",
    "metadata": {
      "couponCode": "SAVE20",
      "giftWrapping": true,
      "giftMessage": "Happy Birthday!"
    },
    "expiresAt": "2025-10-02T15:05:45",
    "createdAt": "2025-10-02T14:30:45",
    "updatedAt": "2025-10-02T14:50:45",
    "completedAt": null,
    "createdOrderId": null,
    "cartId": null
  }
}

~~Success Response Fields~~:

~~Field~~	~~Description~~
~~All fields~~	~~Same as Create Checkout Session response, with updated values~~
~~updatedAt~~	~~Timestamp showing when the session was last updated~~
~~pricing.shippingCost~~	~~May be recalculated if shipping method changed~~
~~pricing.total~~	~~May be recalculated if shipping method changed~~

Error ~~Response JSON Sample~~:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot update - payment has been completed",
  "action_time": "2025-10-02T14:50:45",
  "data": "Cannot update - payment has been completed"
}

~~Error Response Examples~~Responses:

~~Bad Request -~~ Cannot Update Completed Session (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot update a completed checkout session",
  "action_time": "2025-10-02T14:50:45",
  "data": "Cannot update a completed checkout session"
}

~~Bad Request - Cannot Update Cancelled Session (400):~~

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot update a cancelled checkout session",
  "action_time": "2025-10-02T14:50:45",
  "data": "Cannot update a cancelled checkout session"
}

~~Bad Request - Cannot Update Expired Session (400):~~

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot update an expired checkout session",
  "action_time": "2025-10-02T14:50:45",
  "data": "Cannot update an expired checkout session"
}

~~Not Found - Session Not Found (404):~~

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Checkout session not found or you don't have permission to access it",
  "action_time": "2025-10-02T14:50:45",
  "data": "Checkout session not found or you don't have permission to access it"
}

~~Not Found - Payment Method Not Found (404):~~

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Payment method not found or does not belong to you",
  "action_time": "2025-10-02T14:50:45",
  "data": "Payment method not found or does not belong to you"
}

6. Cancel Checkout Session

Purpose: Cancels an existing checkout session and releases held inventory. Cannot cancel sessions that are completed or have successful payment.

Endpoint: DELETE {base_url}/checkout-sessions/{sessionId}/cancel

Access Level: 🔒 Protected (Requires Authentication and Ownership)

~~Authentication~~~~: Bearer Token required in Authorization header~~

~~Request Headers~~:

~~Header~~	~~Type~~	~~Required~~	~~Description~~
~~Authorization~~	~~string~~	~~Yes~~	~~Bearer token for authenticated user~~

~~Path Parameters~~:

~~Parameter~~	~~Type~~	~~Required~~	~~Description~~	~~Validation~~
~~sessionId~~	~~string (UUID)~~	~~Yes~~	~~Unique identifier of the checkout session to cancel~~	~~Valid UUID format~~

Success Response ~~JSON Sample~~:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Checkout session cancelled successfully",
  "action_time": "2025-10-02T14:55:45",
  "data": null
}

~~Success Response Fields~~:

~~Field~~	~~Description~~
~~data~~	~~Always null for cancel operations~~

Error ~~Response JSON Sample~~:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot cancel a completed checkout session",
  "action_time": "2025-10-02T14:55:45",
  "data": "Cannot cancel a completed checkout session"
}

~~Error Response Examples~~Responses:

~~Bad Request -~~ Cannot Cancel Completed ~~Session (400):~~

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot cancel a completed checkout session",
  "action_time": "2025-10-02T14:55:45",
  "data": "Cannot cancel a completed checkout session"
}

~~Bad Request - Cannot Cancel with Successful Payment~~ (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot cancel - payment has been completed. Please contact support.",
  "action_time": "2025-10-02T14:55:45",
  "data": "Cannot cancel - payment has been completed. Please contact support."
}

~~Bad Request -~~ Already Cancelled (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Checkout session is already cancelled",
  "action_time": "2025-10-02T14:55:45",
  "data": "Checkout session is already cancelled"
}

~~Not Found - Session Not Found (404):~~

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Checkout session not found or you don't have permission to access it",
  "action_time": "2025-10-02T14:55:45",
  "data": "Checkout session not found or you don't have permission to access it"
}

7. Process Payment

Purpose: Initiates payment processing for a checkout ~~session. Validates~~ session ~~status,~~in ~~inventory~~PENDING_PAYMENT ~~availability,~~status. ~~and payment method before processing. Delegates~~Routes to the appropriate payment ~~provider~~processor (WALLET, CASH, FREE) based on the session amount and payment ~~method type.~~method.

Endpoint: POST {base_url}/checkout-sessions/{sessionId}/process-payment

Access Level: 🔒 Protected (Requires Authentication and Ownership)

~~Authentication~~~~: Bearer Token required in Authorization header~~

~~Request Headers~~:

~~Header~~	~~Type~~	~~Required~~	~~Description~~
~~Authorization~~	~~string~~	~~Yes~~	~~Bearer token for authenticated user~~

Path Parameters:

Parameter	Type	Required	Description	~~Validation~~
sessionId	string (UUID)	Yes	Unique identifier of the checkout session	~~Valid UUID format~~

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Payment processedcompleted successfully"successfully. Your order is being processed.",
  "action_time": "2025-10-02T15:00:45",
  "data": {
    "success": true,
    "paymentProvider": "WALLET",
    "transactionId": "txn_1234567890abcdef",
    "amount": 285000.00,
    "currency": "TZS",
    "status": "COMPLETED"SUCCESS",
    "message": "Payment successful"completed successfully. Your order is being processed.",
    "checkoutSessionId": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
    "escrowId": "esc-uuid",
    "escrowNumber": "ESC-20251002-001",
    "orderId": "ord-uuid",
    "paymentMethod": "WALLET",
    "processedAt"amountPaid": 285000.00,
    "platformFee": 5700.00,
    "sellerAmount": 279300.00,
    "currency": "2025-10-02T15:00:45",
    "orderId": "ord_9876543210fedcba",
    "receiptUrl": nullTZS"
  }
}

Success Response Fields:

~~(may~~be~~nullfor~~

Field	Description
success	Whether the payment was successful
~~paymentProvider~~status	~~Payment~~SUCCESS, ~~provider~~PENDING, ~~used~~or ~~(WALLET, CASH_ON_DELIVERY, CREDIT_CARD, etc.)~~FAILED
~~transactionId~~checkoutSessionId	~~Unique~~The ~~transaction~~session ~~identifier~~that was paid
~~amount~~escrowId	~~Amount~~Escrow ~~processed~~account inholding ~~TZS~~the funds
~~currency~~	~~Currency code (TZS)~~
~~status~~	~~Payment status (COMPLETED, PENDING, PROCESSING, FAILED)~~
~~message~~escrowNumber	Human-readable ~~payment~~escrow ~~result message~~
~~paymentMethod~~	~~Payment method type used~~
~~processedAt~~	~~Timestamp of payment processing~~reference
orderId	Order or booking ID created after ~~successful~~ payment
~~receiptUrl~~paymentMethod	~~URL~~WALLET, toCASH, ~~payment~~or ~~receipt~~FREE
amountPaid	Total ~~some~~amount ~~payment~~charged ~~methods)~~in TZS
platformFee	Platform fee deducted
sellerAmount	Amount the seller receives
currency	Always TZS

Error ~~Response JSON Sample~~:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot process payment - session status: PAYMENT_COMPLETED",
  "action_time": "2025-10-02T15:00:45",
  "data": "Cannot process payment - session status: PAYMENT_COMPLETED"
}

~~Error Response Examples~~Responses:

~~Bad Request - Invalid~~ Session ~~Status~~Not in PENDING_PAYMENT status (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot process payment - session status:is not pending: PAYMENT_COMPLETED",
  "action_time": "2025-10-02T15:00:45",
  "data": "Cannot process payment - session status:is not pending: PAYMENT_COMPLETED"
}

~~Bad Request -~~ Session Expired (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Checkout session has expired",
  "action_time": "2025-10-02T15:00:45",
  "data": "Checkout session has expired"
}

~~Bad Request - Insufficient Wallet Balance (400):~~

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Insufficient wallet balance. Required: 285000 TZS, Available: 150000 TZS",
  "action_time": "2025-10-02T15:00:45",
  "data": "Insufficient wallet balance. Required: 285000 TZS, Available: 150000 TZS"
}

~~Not Found - Session Not Found (404):~~

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Checkout session not found or you don't have permission to access it",
  "action_time": "2025-10-02T15:00:45",
  "data": "Checkout session not found or you don't have permission to access it"
}

8. Retry Payment

Purpose: Retries payment for a ~~failed checkout session. Validates that the~~ session is in PAYMENT_FAILED ~~status, hasn't exceeded maximum retry attempts (5), and hasn't expired.~~status. Re-validates inventory ~~availability~~availability, checks wallet balance, re-holds inventory, and extends session expiration before retrying. Maximum 5 total attempts.

Endpoint: POST {base_url}/checkout-sessions/{sessionId}/retry-payment

Access Level: 🔒 Protected (Requires Authentication and Ownership)

~~Authentication~~~~: Bearer Token required in Authorization header~~

~~Request Headers~~:

~~Header~~	~~Type~~	~~Required~~	~~Description~~
~~Authorization~~	~~string~~	~~Yes~~	~~Bearer token for authenticated user~~

~~Path Parameters~~:

~~Parameter~~	~~Type~~	~~Required~~	~~Description~~	~~Validation~~
~~sessionId~~	~~string (UUID)~~	~~Yes~~	~~Unique identifier of the checkout session~~	~~Valid UUID format~~

~~Success Response JSON Sample~~:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Payment retry successful",
  "action_time": "2025-10-02T15:10:45",
  "data": {
    "success": true,
    "paymentProvider": "WALLET",
    "transactionId": "txn_retry_1234567890abcdef",
    "amount": 285000.00,
    "currency": "TZS",
    "status": "COMPLETED",
    "message": "Payment successful on retry",
    "paymentMethod": "WALLET",
    "processedAt": "2025-10-02T15:10:45",
    "orderId": "ord_retry_9876543210fedcba",
    "receiptUrl": null
  }
}

~~Success Response Fields~~:

~~Field~~	~~Description~~
~~success~~	~~Whether the payment retry was successful~~
~~paymentProvider~~	~~Payment provider used~~
~~transactionId~~	~~Unique transaction identifier for this retry~~
~~amount~~	~~Amount processed in TZS~~
~~currency~~	~~Currency code (TZS)~~
~~status~~	~~Payment status (COMPLETED, PENDING, PROCESSING, FAILED)~~
~~message~~	~~Human-readable payment result message~~
~~paymentMethod~~	~~Payment method type used~~
~~processedAt~~	~~Timestamp of payment processing~~
~~orderId~~	~~Order ID created after successful payment~~
~~receiptUrl~~	~~URL to payment receipt (may be null)~~

Error ~~Response JSON Sample~~:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot retry payment - session status: PENDING_PAYMENT. Expected: PAYMENT_FAILED",
  "action_time": "2025-10-02T15:10:45",
  "data": "Cannot retry payment - session status: PENDING_PAYMENT. Expected: PAYMENT_FAILED"
}

~~Error Response Examples~~Responses:

~~Bad Request -~~ Invalid Status (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot retry payment - session status: PENDING_PAYMENT. Expected: PAYMENT_FAILED",
  "action_time": "2025-10-02T15:10:45",
  "data": "Cannot retry payment - session status: PENDING_PAYMENT. Expected: PAYMENT_FAILED"
}

~~Bad Request - Session Expired (400):~~

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Checkout session has expired. Please create a new checkout session.",
  "action_time": "2025-10-02T15:10:45",
  "data": "Checkout session has expired. Please create a new checkout session."
}

~~Bad Request -~~ Max ~~Retry~~ Attempts Exceeded (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Maximum payment attempts (5) exceeded. Please create a new checkout session.",
  "action_time": "2025-10-02T15:10:45",
  "data": "Maximum payment attempts (5) exceeded. Please create a new checkout session."
}

~~Bad~~Insufficient ~~Request~~Wallet -Balance on Retry (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Insufficient wallet balance. Required: 285000 TZS, Available: 150000 TZS. Please top up your wallet.",
  "action_time": "2025-10-02T15:10:45",
  "data": "Insufficient wallet balance. Required: 285000 TZS, Available: 150000 TZS. Please top up your wallet."
}

Product No Longer Available (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Product 'Premium Wireless Headphones' is no longer available in requested quantity. Please create a new checkout session.",
  "action_time": "2025-10-02T15:10:45",
  "data": "Product 'Premium Wireless Headphones' is no longer available in requested quantity. Please create a new checkout session."
}

~~Bad Request - Insufficient Wallet Balance (400):~~

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Insufficient wallet balance. Required: 285000 TZS, Available: 150000 TZS. Please top up your wallet or update your payment method.",
  "action_time": "2025-10-02T15:10:45",
  "data": "Insufficient wallet balance. Required: 285000 TZS, Available: 150000 TZS. Please top up your wallet or update your payment method."
}

~~Not Found - Session Not Found (404):~~

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Checkout session not found or you don't have permission to access it",
  "action_time": "2025-10-02T15:10:45",
  "data": "Checkout session not found or you don't have permission to access it"
}

Checkout Session Types

REGULAR_DIRECTLY

Direct product purchase without using a cart. Must include exactly 1 ~~item in the request.~~

~~Characteristics:~~item.

~~Single item purchase flow~~

~~Items array must contain exactly 1 product~~

~~Does not link to any cart~~

~~cartId field will be null in response~~
Best for "Buy Now" buttons

Balance ~~quick~~is ~~checkout~~checked ~~flows~~against pricing.total (includes shipping)

Inventory is held immediately on session creation

~~Example Use Case:~~ ~~User clicks "Buy Now" on a product detail page and proceeds directly to checkout.~~

REGULAR_CART

Checkout from existing shopping cart. Items are ~~retrieved~~fetched automatically from the user's active cart.

~~Characteristics:~~

Multi-item purchase flow
Items array not required in request

Balance is checked against pricing.total (~~fetched~~includes ~~from~~shipping)

Inventory is held for all cart ~~automatically)~~

~~Links to user's cart via cartId~~

~~Cart is validated before checkout creation~~

~~cartId field will be populated in response~~items

~~Example Use Case:~~ ~~User adds multiple products to cart, reviews cart, and clicks "Proceed to Checkout".~~

GROUP_PURCHASE

~~Special~~Group buying checkout ~~type for group buying~~ where multiple users purchase the same product at a discounted group price.

~~Characteristics:~~

Single item ~~purchase~~ at ~~group price~~product.groupPrice
~~Items~~Balance ~~array~~is ~~must~~checked ~~contain~~against ~~exactly~~groupPrice 1× productquantity
~~Payment~~WALLET payment method ~~MUST be WALLET (other methods not supported)~~only
Can join existing group ~~via~~(provide groupInstanceId) or create new group (provide groupName)
~~Uses~~No ~~product's~~session-level ~~groupPrice~~inventory ~~instead~~hold of— ~~regular~~inventory ~~price~~

~~Requires~~held ~~product~~at tothe ~~have~~group ~~groupBuyingEnabled~~level =after ~~true~~

~~Quantity cannot exceed product's groupMaxSize~~

~~Group has time limit defined by product's groupTimeLimitHours~~payment

~~Example Use Case:~~ ~~User sees a product available for group buying at 80,000 TZS (regular price: 150,000 TZS). User can either start a new group or join an existing group with available seats.~~

~~Request Example (~~Create New ~~Group):~~Group:

{
  "sessionType": "GROUP_PURCHASE",
  "items": [{ "productId": "prod-uuid", "quantity": 2 }],
  "shippingAddressId": "addr-uuid",
  "groupName":"This is my winning group",
  "shippingMethodId": "standard",
  "paymentMethodId"groupName": null,"My "groupInstanceId":Winning nullGroup"
}

~~Request Example (~~Join Existing ~~Group):~~Group:

{
  "sessionType": "GROUP_PURCHASE",
  "items": [{ "productId": "prod-uuid", "quantity": 3 }],
  "shippingAddressId": "addr-uuid",
  "shippingMethodId": "standard",
  "paymentMethodId": null,
  "groupInstanceId": "group-uuid-to-join"
}

INSTALLMENT

~~Status:~~ ~~PLACEHOLDER - Not Yet Implemented~~

~~Future checkout type for installment~~Split payment ~~plans.~~over ~~Will~~multiple ~~allow~~months. ~~users~~Only tothe ~~split~~down payment is charged at checkout; remaining monthly payments ~~into~~are ~~multiple~~processed ~~installments.~~

automatically

~~Planned~~by ~~Characteristics:~~the scheduler.

~~Will~~Balance ~~require~~is checked against downPaymentAmount only (not the full product price)

installmentPlanId and downPaymentPercent are required

pricing.total in ~~request~~

the

~~Payment~~session ~~spread~~response ~~over~~reflects ~~multiple periods~~

~~May require~~the down payment only
~~Interest~~Inventory ~~rates~~is ~~may~~held ~~apply based~~immediately on ~~plan~~

session

~~Credit check may be required~~creation

~~Current Behavior:~~ ~~Returns error:~~

{
  "INSTALLMENTsessionType": checkout"INSTALLMENT",
  not"items": implemented[{ yet"
"productId": "prod-uuid", "quantity": 1 }],
  "shippingAddressId": "addr-uuid",
  "shippingMethodId": "standard",
  "installmentPlanId": "plan-uuid",
  "downPaymentPercent": 20
}

Checkout Session Status Flow

Status Definitions

Status	Description	Can Update?	Can Cancel?	Can Pay?	Can Retry?
PENDING_PAYMENT	Session created, awaiting payment	Yes	Yes	Yes	No
PAYMENT_PROCESSING	Payment in progress	No	No	No	No
PAYMENT_FAILED	Payment failed, can retry	Yes	Yes	No	Yes
PAYMENT_COMPLETED	Payment successful	No	No	No	No
EXPIRED	Session expired	No	No	No	No
CANCELLED	User cancelled	No	No	No	No
COMPLETED	~~Order~~Free/cash ~~created~~order ~~successfully~~completed	No	No	No	No

Status Transition Flow

[Session Creation]
        |
        | balance check passes
        v
PENDING_PAYMENT
    ├|
    |-- user cancels ──────────────────> PAYMENT_PROCESSINGCANCELLED
    |                                    (wheninventory paymentreleased)
    initiated)|
    │|-- ├15 min timeout ────────────────> PAYMENT_COMPLETEDEXPIRED
    |                                    (oninventory success)released)
    │|
    │|-- └processPayment()
        |
        |-- amount = 0 ────────────────> COMPLETED (afterfree)
        order|
        creation)|-- │CASH └──────────────────────> COMPLETED (cash)
        |
        |-- WALLET ────────────────────> PAYMENT_PROCESSING
                                                |
                                                |-- success ──> PAYMENT_COMPLETED
                                                |                (order/booking created,
                                                |                 inventory committed)
                                                |
                                                |-- failure ──> PAYMENT_FAILED
                                                                (oninventory failure,released canfor retryevents,
                                                                 max 5 times)retries)
                                                                │|
                                                                ├|-- retryPayment() ──> PENDING_PAYMENT
                                                                |                     (wheninventory retryre-held)
                                                                initiated)|
                                                                │|-- └5 attempts ──────> EXPIRED
(after

~~max~~

~~retries~~

Wallet orBalance Check Endpoint

For cases where the frontend wants to proactively check balance against an existing session ~~timeout)~~(e.g., ~~├─>~~before ~~CANCELLED~~showing ~~(user~~the ~~cancels)~~"Pay ~~└─>~~Now" ~~EXPIRED~~button), ~~(15~~use:

~~minutes~~

Endpoint: ~~timeout)~~GET {base_url}/wallet/checkout-balance-check?sessionId={id}&domain={PRODUCT|EVENT}

Success Response:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Checkout balance check completed",
  "data": {
    "walletBalance": 150000.00,
    "sessionTotal": 285000.00,
    "shortfall": 135000.00,
    "hasSufficientBalance": false,
    "recommendedTopUp": 135000.00,
    "pspMinimum": 500.00,
    "currency": "TZS"
  }
}

Note: This endpoint always returns 200 — it never throws. Use hasSufficientBalance to determine if the user can pay. This is the "soft check" for an existing session; the "hard check" (which blocks session creation) happens automatically inside POST /checkout-sessions.

Payment Methods Supported

WALLET (Default)

Internal wallet ~~system~~system. ~~for~~Default ~~storing~~if ~~and~~no ~~using~~payment ~~funds.~~

method

~~Requirements:~~is specified.

~~User must have active wallet~~

~~Sufficient balance required~~

Balance ~~checked~~validated ~~before~~at session creation (hard block) and again at payment ~~processing~~time (safety net)
Instant ~~payment~~processing ~~processing~~via escrow
NoFunds ~~additional~~held ~~fees~~in escrow until order is confirmed/delivered

~~Payment Flow:~~

~~Validate wallet is active~~

~~Check sufficient balance~~

~~Deduct amount from wallet~~

~~Create transaction record~~

~~Create order~~

~~Default Behavior:~~ ~~If no paymentMethodId provided in request, WALLET is used as default.~~

CASH_ON_DELIVERYCASH

Pay in cash ~~when~~on ~~order~~delivery isor ~~delivered.~~

~~Requirements:~~the point of event check-in.

No pre-payment required
~~Payment collected by delivery agent~~

~~Order~~Order/booking created immediately
~~May~~Applicable ~~have~~to ~~geographic~~both ~~restrictions~~product and event checkouts

FREE

~~Payment~~Zero-amount ~~Flow:~~checkout (free products or free event tickets).

~~Create~~Handled automatically when pricing.total = 0

No payment ~~intent~~method ~~with status "PENDING"~~required
~~Create~~Order/booking ~~order~~created immediately
~~Payment marked as "COD"~~

~~Delivery agent collects payment on delivery~~

CREDIT_CARD / DEBIT_CARDMOBILE_MONEY

Status: Planned -— ~~Not~~not ~~Yet~~yet ~~Implemented~~

~~Future support for credit and debit card payments.~~

~~Planned Features:~~

~~Card tokenization for security~~

~~PCI compliance~~

~~3D Secure authentication~~

~~Saved cards support~~

~~International cards support~~

MNO_PAYMENT (Mobile Money)

~~Status:~~ ~~Planned - Not Yet Implemented~~

~~Future support for mobile money payments (M-Pesa, Tigo Pesa, Airtel Money, etc.).~~

~~Planned Features:~~

~~USSD push notifications~~

~~Callback confirmation~~

~~Transaction reconciliation~~

~~Multiple operators support~~

Other Payment Methods

~~Additional payment methods (PayPal, Bank Transfer, Cryptocurrency, Gift Card) are placeholders for future implementation.~~implemented.

Inventory Management

Inventory Hold Mechanism

Session Type	Hold Created At	Hold Released At
REGULAR_DIRECTLY	Session creation	Expiry, cancellation, or payment success (committed)
REGULAR_CART	Session creation	Expiry, cancellation, or payment success (committed)
GROUP_PURCHASE	After payment, at group level	Group expiry or group failure
INSTALLMENT	Session creation	Expiry, cancellation, or payment success (committed)

~~When~~On asuccessful ~~checkout~~payment, ~~session~~holds isare ~~created,~~committed ~~inventory~~(stock ispermanently ~~automatically~~deducted). ~~held~~On failure/expiry/cancellation, holds are released (stock returned to ~~prevent overselling.~~

~~Hold Behavior:~~

~~Inventory held for 15 minutes (matches session expiration)~~

~~Held quantity deducted from available stock~~

~~Other users cannot purchase held inventory~~

~~Hold automatically released on:~~
- ~~Session expiration~~
- ~~Session cancellation~~
- ~~Payment failure (after 5 retry attempts)~~

~~Hold converted to permanent deduction on successful payment~~

~~Hold Fields:~~

inventoryHeld~~: Boolean indicating if inventory is currently held~~

inventoryHoldExpiresAt~~: Timestamp when hold will be released~~

~~Example:~~

{
  "inventoryHeld": true,
  "inventoryHoldExpiresAt": "2025-10-02T14:45:45"
}

Inventory Validation

~~Before processing payment or retry, system validates:~~

~~Product still exists and is active~~

~~Product still in stock~~

~~Requested quantity still available~~

~~Product hasn't been deleted~~

~~If validation fails, user must create new checkout session with current availability.~~available).

Session Expiration

Expiration Rules

~~Default Expiration:~~Default: 15 minutes from ~~creation~~creation.

~~Expiration~~ Extended ~~When:~~when:

Payment retry is initiated (adds 15 minutes)

~~Session updated successfully (adds 15 minutes)~~

~~What~~On ~~Happens on Expiration:~~expiry:

~~Session~~Status ~~status changes to~~→ EXPIRED
Held inventory released ~~back to available stock~~
Session cannot be ~~updated~~updated, paid, or ~~paid~~

~~Session cannot be~~ cancelled ~~(already effectively ended)~~
User must create ~~new checkout session~~

~~Checking Expiration:~~

expiresAt ~~field shows expiration timestamp~~

isExpired ~~field (in summary responses) shows if session expired~~

Preventing Expiration

~~To prevent session expiration:~~

~~Complete payment before expiration~~

~~Update session if needed (extends timer)~~

~~If expired, create~~a new checkout session

~~Best Practice:~~ ~~Display countdown timer to users showing time remaining before expiration.~~

Payment Attempts Tracking

Attempt Limits

Maximum ~~Attempts:~~ 5 attempts per ~~session~~

~~Attempt Tracking:~~session. Each ~~payment~~ attempt ~~recorded with:~~records:

Attempt number (1-1–5)
Payment method used
~~Status~~Status: (SUCCESS, FAILED, ~~RETRY_INITIATED)~~or RETRY_INITIATED
Error message (if failed)
Timestamp
~~Transaction~~and transaction ID ~~(if available)~~

~~Example Payment Attempts:~~

{
  "paymentAttempts": [
    {
      "attemptNumber": 1,
      "paymentMethod": "WALLET",
      "status": "FAILED",
      "errorMessage": "Insufficient wallet balance",
      "attemptedAt": "2025-10-02T14:35:00",
      "transactionId": null
    },
    {
      "attemptNumber": 2,
      "paymentMethod": "WALLET",
      "status": "RETRY_INITIATED",
      "errorMessage": null,
      "attemptedAt": "2025-10-02T14:40:00",
      "transactionId": null
    },
    {
      "attemptNumber": 3,
      "paymentMethod": "WALLET",
      "status": "SUCCESS",
      "errorMessage": null,
      "attemptedAt": "2025-10-02T14:42:00",
      "transactionId": "txn_1234567890abcdef"
    }
  ]
}

After Max Attempts

~~When~~ 5 ~~attempts~~failed ~~exceeded:~~

attempts,

~~Session~~session status ~~set~~moves to EXPIRED
~~Inventory~~and ~~released~~

inventory

~~Cannot~~is ~~retry payment~~

~~User must create new checkout session~~

Metadata Usage

Purpose

~~Metadata allows storing custom key-value data with checkout sessions for business-specific needs.~~released.

Common Use Cases

~~Coupons & Discounts:~~

{
  "metadata": {
    "couponCode": "SAVE20",
    "couponDiscount": 20000,
    "couponAppliedAt": "2025-10-02T14:30:00"
  }
}

~~Referral Tracking:~~

{
  "metadata": {
    "referralCode": "REF123",
    "referredBy": "user-uuid",
    "referralBonus": 5000
  }
}

~~Gift Options:~~

{
  "metadata": {
    "isGift": true,
    "giftWrapping": true,
    "giftMessage": "Happy Birthday!",
    "giftRecipientName": "Jane Doe"
  }
}

~~Delivery Instructions:~~

{
  "metadata": {
    "deliveryInstructions": "Leave package at front desk",
    "deliveryTimePreference": "morning",
    "contactOnArrival": true
  }
}

~~Group Purchase:~~

{
  "metadata": {
    "groupInstanceId": "group-uuid",
    "isGroupLeader": true,
    "groupCreatedAt": "2025-10-02T14:30:00"
  }
}

~~Marketing Attribution:~~

{
  "metadata": {
    "source": "facebook_ad",
    "campaign": "summer_sale_2025",
    "medium": "social_media"
  }
}

Metadata Rules

~~Stored as JSON object~~

~~Key-value pairs with string keys~~

~~Values can be strings, numbers, booleans, or nested objects~~

~~No size limit enforced at API level (reasonable usage expected)~~

~~Merged with existing metadata on update (not replaced)~~

~~Persisted with session throughout lifecycle~~

~~Accessible in order after completion~~

Error Handling Best Practices

Client-SideFrontend HandlingChecklist

Before ~~Creating~~calling ~~Checkout:~~POST /checkout-sessions:

~~Validate~~Ensure the user has a shipping address saved
~~Check~~No ~~product~~need ~~availability~~to pre-check balance — the API returns rich balance data if insufficient

On 422 Insufficient Balance response:

Read data.shortfall to show how much the user is short
~~Verify~~Read ~~payment~~data.recommendedTopUp ~~method~~to ~~exists~~pre-fill ~~(if~~a top-up amount

Navigate the user to the wallet top-up screen

Once topped up, retry POST /checkout-sessions — do not ~~using~~store ~~wallet)~~the failed session
~~Display clear pricing breakdown~~

During ~~Checkout:~~active session (PENDING_PAYMENT):

Show ~~expiration~~a countdown timer using expiresAt
~~Handle~~On expiry, prompt user to create a new session ~~expiration gracefully~~
~~Provide clear error messages~~

~~Suggest actions (e.g., "Top up wallet" if insufficient balance)~~

~~Payment~~On ~~Failures:~~payment failure:

~~Display~~Show ~~specific~~canRetryPayment ~~error~~to ~~reason~~decide whether to show a retry button
Show remaining ~~retry~~attempts ~~attempts~~(5 - paymentAttemptCount)
~~Offer~~On retry, call POST /{sessionId}/retry-payment — no need to ~~update payment method~~

~~Suggest alternative payment methods~~

Common Error Scenarios

~~Insufficient Inventory:~~

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Insufficient stock. Available: 3, Requested: 5"
}

~~Action:~~ ~~Reduce quantity or create new session with available quantity.~~

~~Insufficient Wallet Balance:~~

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Insufficient wallet balance. Required: 285000 TZS, Available: 150000 TZS"
}

~~Action:~~ ~~Top up wallet or change payment method.~~

~~Session Expired:~~

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Checkout session has expired"
}

~~Action:~~ ~~Create new checkout session.~~

~~Product Unavailable:~~

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Product is not available for purchase"
}

~~Action:~~ ~~Remove product from cart or select alternative product.~~

~~Max Retries Exceeded:~~

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Maximum payment attempts (5) exceeded. Please create a new checkoutsession
session."
}

~~Action:~~ ~~Create new checkout session, possibly with different payment method.~~

Integration Examples

Example 1: Direct Product Purchase Flow

~~Step 1: Create Checkout Session~~

1. POST /api/v1/checkout-sessions
   Authorization:→ Bearer422 {token}if Content-Type:balance application/jsoninsufficient {(show "sessionType":top-up "REGULAR_DIRECTLY",screen "items":with [{data.recommendedTopUp)
   "productId":→ "prod-uuid",201 "quantity":with 1sessionId }],if "shippingAddressId":balance "addr-uuid",OK

"shippingMethodId":2. "standard",
  "paymentMethodId": null
}

~~Step 2: Process Payment~~

POST /api/v1/checkout-sessions/{sessionId}/process-payment
   Authorization:→ Bearer200 {token}with orderId on success

~~Step 3: Check Order Created~~ ~~Response will include~~ orderId ~~field after successful payment.~~

Example 2: Cart Checkout Flow

~~Step 1: Create Checkout from Cart~~

1. POST /api/v1/checkout-sessions  Authorization: Bearer {token}
Content-Type: application/json

{ "sessionType":sessionType: "REGULAR_CART",REGULAR_CART, "shippingAddressId": "addr-uuid",
  "shippingMethodId": "express",
  "metadata": {
    "couponCode": "SAVE20"... }
   }→

422

~~Step~~or 2:201 ~~Review~~2. ~~Session~~

(optional)

GETPATCH /api/v1/checkout-sessions/{sessionId}  Authorization: Bearer {token}

~~Step 3: Update if Needed~~

PATCH /api/v1/checkout-sessions/{sessionId}
Authorization: Bearer {token}
Content-Type: application/json

{ "shippingMethodId":shippingMethodId: "standard",
  "metadata": {
    "giftWrapping": trueexpress" }

}3.

~~Step 4: Process Payment~~

POST /api/v1/checkout-sessions/{sessionId}/process-payment
Authorization: Bearer {token}

Example 3: Group Purchase Flow

~~Step 1: Create Group Purchase Session~~

1. POST /api/v1/checkout-sessions  Authorization: Bearer {token}
Content-Type: application/json

{ "sessionType":sessionType: GROUP_PURCHASE, groupName: "GROUP_PURCHASE"...", "items": [{
    "productId": "prod-uuid",
    "quantity": 2
  }],
  "shippingAddressId": "addr-uuid",
  "shippingMethodId": "standard",
  "groupInstanceId": null... }

→

~~Step~~422 2:if ~~Process~~balance ~~Payment~~< ~~(WALLET~~groupPrice ~~only)~~

qty
   → 201 with sessionId

2. POST /api/v1/checkout-sessions/{sessionId}/process-payment
   Authorization:(WALLET Bearer {token}only)

Example 4: Installment

1. POST /checkout-sessions  { sessionType: INSTALLMENT, installmentPlanId: "...", downPaymentPercent: 20 }
   → 422 if balance < downPaymentAmount
   → 201 with sessionId (pricing.total = down payment only)

2. POST /checkout-sessions/{sessionId}/process-payment
   → charges down payment only; monthly payments handled by scheduler

Example 5: Payment Retry Flow

~~Step 1: Get Active Sessions~~

1. GET /api/v1/checkout-sessions/active
   Authorization:→ Bearer {token}

~~Step 2: Identify Failed Session~~ ~~Look for~~find session with status: "PAYMENT_FAILED"PAYMENT_FAILED, ~~and~~ canRetryPayment: true

~~Step~~2. ~~3: Update Payment Method (Optional)~~

PATCH /api/v1/checkout-sessions/{sessionId}
Authorization: Bearer {token}
Content-Type: application/json

{
  "paymentMethodId": "new-payment-method-uuid"
}

~~Step 4: Retry Payment~~

POST /api/v1/checkout-sessions/{sessionId}/retry-payment
   Authorization:→ Bearerre-validates {token}inventory + balance
   → re-holds inventory
   → processes payment

Rate Limiting

~~Rate~~

~~Limits:~~

~~Process/~~

~~Update/Cancel:~~

~~Rate~~

~~Limit Headers:~~

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 15
X-RateLimit-Reset: 1696258800

~~Rate Limit Exceeded:~~

{
  "success": false,
  "httpStatus": "TOO_MANY_REQUESTS",
  "message": "Rate limit exceeded. Please try again later.",
  "action_time": "2025-10-02T15:30:45",
  "data": "Rate limit exceeded. Please try again later."
}

Endpoint	Limit
Create ~~Checkout:~~Checkout	20 ~~requests per minute~~req/min per user
Get ~~Sessions:~~Sessions	60 ~~requests per minute~~req/min per user
Process / Retry ~~Payment:~~Payment	10 ~~requests per minute~~req/min per user
Update / Cancel	30 ~~requests per minute~~req/min per user