check order status

while webhooks are the recommended mechanism to receive transaction state updates, you can also query the status of a specific order manually by invoking our secure GET status endpoint.

this is particularly useful for building self-healing checkout sessions (e.g., verifying an order's state when a customer returns to your storefront but your server has not yet processed the corresponding webhook).

---

endpoint details

• HTTP Method: GET
• Production URL: https://api.divit.com.hk/paynow/orders/{orderID}/status
• Sandbox URL: https://sandbox-api.divit.dev/paynow/orders/{orderID}/status

headers

api-key: your_api_key_here
Content-Type: application/json

---

implementation examples

we recommend utilizing modern async/await patterns. below is an example using Node's native fetch API:

/**
 * Queries the current transaction status from Divit
 * @param {string} orderID - Divit's unique Order UUID
 * @param {string} apiKey - Your secret merchant API key
 * @returns {Promise<object>} - Order status payload
 */
async function checkOrderStatus(orderID, apiKey) {
  const baseUrl = "https://sandbox-api.divit.dev"; // Use production URL for live transactions
  const url = `${baseUrl}/paynow/orders/${orderID}/status`;

  try {
    const response = await fetch(url, {
      method: "GET",
      headers: {
        "api-key": apiKey,
        "Content-Type": "application/json"
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP Error: ${response.status}`);
    }

    const payload = await response.json();
    return payload;
  } catch (error) {
    console.error("Failed to fetch order status:", error);
    throw error;
  }
}

---

success response structure

when successfully queried, the endpoint returns details on the current transaction status, settled amounts, processing fees, and refund details.

{
  "code": 0,
  "message": "OK",
  "data": {
    "orderID": "c3222a2f-2908-468d-b0a8-7c64f3a21b4c",
    "merchantRef": "ORDER-10024A",
    "orderAmount": {
      "amount": 40000,
      "currency": "HKD"
    },
    "status": "completed",
    "merchantFee": {
      "amount": 400,
      "currency": "HKD"
    },
    "customerFee": {
      "amount": 0,
      "currency": "HKD"
    },
    "totalRefundRequested": {
      "amount": 15000,
      "currency": "HKD"
    },
    "totalRefundCompleted": {
      "amount": 0,
      "currency": "HKD"
    },
    "instalments": [
      {
        "instalmentSeriesID": 1,
        "status": "paid",
        "instalmentAmount": {
          "amount": 40000,
          "currency": "HKD"
        }
      }
    ]
  }
}

response property reference

• status (string): the current state of the order. possible values are:
  • new: order generated but not yet accessed by the customer.
  • active: customer has opened the checkout screen.
  • completed: payment successfully settled.
  • expired: checkout window closed without payment.
  • cancelled: the transaction was aborted.
• orderAmount (object): total order cost details (in smallest subunits).
• merchantFee (object): settlement processing fees applied to the merchant for this transaction.
• customerFee (object): processing fees applied to the customer (typically 0 for FPS payments).
• totalRefundRequested (object): cumulative amount of refunds requested for this order.
• totalRefundCompleted (object): cumulative amount of refunds successfully executed and settled.