API Reference

Post Checkout Webhook

Receive real-time order status notifications from deema after checkout completion.

deema sends a webhook notification to your configured endpoint whenever an order's status changes after checkout.

Use this webhook to keep your system synchronized with real-time payment events across both

Sandbox and Production environments.


Overview

After a customer completes a checkout session (online or in-store), deema dispatches POST requests to your registered webhook URL each time the order transitions to a new status.

This enables your application to react immediately to payment confirmations, cancellations, refunds, and other lifecycle events , without polling the API.

🔔

The webhook payload structure remains consistent across both environments.

Configure your webhook URL in the deema Merchant Dashboard under Settings → Webhooks for each environment independently.

Environments

EnvironmentBase DomainPurpose
Sandboxhttps://sandbox-api.deema.meTest and validate your webhook integration
Productionhttps://api.deema.meReceive live payment event notifications
⚠️

Always test your webhook handler thoroughly in Sandbox before enabling it in Production.

Sandbox payloads mirror the production format, allowing you to verify your integration without affecting real transactions.


Webhook Payload

deema sends a JSON payload via POST to your registered webhook URL.

The payload contains the core order identifiers and the current order status.

Sample Payload

{
  "merchant_order_ref": "INV-40",
  "order_ref": "112cee08-766e-4cce-bb45-e94fa7e294ae",
  "status": "captured",
  "purchase_id": 5080
}

Payload Fields

FieldTypeDescription
merchant_order_refstringThe unique order identifier from your system, as provided during checkout creation via the merchant_order_id parameter.
order_refstringThe unique deema order reference (UUID) assigned to the transaction. Use this value to retrieve full order details via the Order Details API.
statusstringThe current status of the order. See Order Statuses for the complete list of possible values.
purchase_idintegerThe deema internal purchase identifier associated with the transaction.
📌

The payload may vary depending on the order's lifecycle stage.

Fields such as status and associated amounts will reflect the most recent state of the transaction at the time of dispatch.


Order Status Reference

The status field in the webhook payload corresponds to one of the defined order statuses in the deema platform. Each status represents a specific stage in the order lifecycle , from initial creation through to capture, refund, or cancellation.

For the complete list of all possible status values and their definitions, refer to the Order Statuses page.


Handling the Webhook

Follow these steps to process incoming webhook notifications reliably:

  1. Expose an HTTPS endpoint on your server that accepts POST requests with a JSON body.

  2. Parse the JSON payload and extract the order_ref, merchant_order_ref, status, and purchase_id fields.

  3. Match the order in your system using merchant_order_ref (your internal order ID) or order_ref (deema's reference).

  4. Update your order status based on the received status value. Implement logic for each relevant status transition your business requires.

  5. Respond with an HTTP 200 OK to acknowledge receipt. \n\n If deema does not receive a successful response, the webhook delivery will be retried.

Example: Webhook Handler

const express = require("express");
const app = express();

app.use(express.json());

app.post("/webhooks/deema", (req, res) => {
  const { merchant_order_ref, order_ref, status, purchase_id } = req.body;

  console.log(`Order ${merchant_order_ref} is now: ${status}`);

  // Update order status in your database
  switch (status) {
    case "captured":
      // Payment was successfully captured — fulfill the order
      break;
    case "fully_refunded":
      // Full refund issued — update records accordingly
      break;
    case "partially_refunded":
      // Partial refund issued — adjust the order amount
      break;
    case "payment_cancelled":
      // Order was cancelled — release reserved inventory
      break;
    default:
      console.log(`Received status: ${status} for order ${order_ref}`);
  }

  // Acknowledge receipt to Deema
  res.status(200).json({ received: true });
});

app.listen(3000, () => console.log("Webhook listener running on port 3000"));

Best Practices

  • Always respond with HTTP 200 — Return a 200 OK status immediately upon receiving the webhook, even if your internal processing takes time. Perform heavy operations asynchronously to avoid timeouts.

  • Implement idempotency — deema may send the same webhook more than once in retry scenarios. Use the order_ref to deduplicate events and prevent processing the same status change twice.

  • Validate the payload — Verify that all expected fields (merchant_order_ref, order_ref, status, purchase_id) are present before processing.

  • Log all incoming payloads — Maintain a record of every webhook received for auditing, debugging, and dispute resolution purposes.

  • Use HTTPS — Ensure your webhook endpoint uses HTTPS to protect the transmitted data in transit.

  • Handle all statuses — Design your webhook handler to account for every status defined in the Order Statuses reference, including statuses you may not actively use today, to avoid unexpected failures as your integration evolves.