refund request

if you need to execute a full or partial refund on an order, you can use our Refund Request API.

divit handles refunds securely. once a refund is requested, the system automatically queues and processes it. depending on your merchant account's settlement settings, refunds are typically finalized on the next business day by 16:00 HKT.

---

endpoint details

• HTTP Method: POST
• Production URL: https://api.divit.com.hk/paynow/orders/refund/request
• Sandbox URL: https://sandbox-api.divit.dev/paynow/orders/refund/request

headers

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

---

request parameters

the body of the POST request must be a JSON object containing:

Parameter	Type	Required	Description
orderID	string	Yes	divit's unique Order UUID of the transaction you wish to refund.
refundType	string	Yes	specify either "full" or "partial".
refundAmount	number	Yes	the absolute refund amount as a decimal float (e.g., 100.50 for HKD $100.50).
callbackURI	string	No	a secure webhook URL where divit will dispatch refund progress notifications.
remarks	string	No	optional notes or justification for the refund.

---

implementation example

below is a backend implementation example using Node's modern fetch API:

/**
 * Submits a refund request to Divit
 * @param {object} refundData - Refund details
 * @param {string} apiKey - Your secret merchant API key
 * @returns {Promise<object>} - API response
 */
async function requestRefund(refundData, apiKey) {
  const url = "https://sandbox-api.divit.dev/paynow/orders/refund/request";

  try {
    const response = await fetch(url, {
      method: "POST",
      headers: {
        "api-key": apiKey,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(refundData)
    });

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

    return await response.json();
  } catch (error) {
    console.error("Refund request failed:", error);
    throw error;
  }
}

// Usage Example
// requestRefund({
//   orderID: "956db0a3-68b1-420c-9df9-3ec5d77136b9",
//   refundType: "partial",
//   refundAmount: 100.50,
//   callbackURI: "https://your-api.com/webhooks/divit-refunds",
//   remarks: "Customer requested return"
// }, "your_api_key");

---

processing considerations

key constraints & rules

1. next-day processing: refunds typically complete by 16:00 HKT on the next business day.
2. sufficient balance: refunds are covered by your unsettled/pending merchant balance. if your pending balance is lower than the requested refund amount, the refund request will remain queued until additional transactions replenish your balance.

---

refund webhook callbacks

if a callbackURI is specified in the request, divit will notify your server of state changes using the same signature format (X-DIVIT-SIGNATURE) as order webhooks.

refund callback events

Event ID	Title	Description
2100	refund completed	the refund transaction was successfully processed and settled back to the customer's bank account.
4100	refund cancelled	the refund request failed, was aborted, or rejected due to insufficient balance.

refund webhook event payload example

{
  "event": {
    "eventId": 2100,
    "eventDescription": "Refund is completed"
  },
  "eventData": {
    "orderID": "7f32674f-6f8a-407d-934c-768d84472a76",
    "partnerRef": "ORDER-10024A",
    "refundAmount": {
      "amount": 10050,
      "currency": "HKD"
    },
    "status": "completed"
  }
}