Webhooks
Overview
Webhooks are real-time HTTP notifications that DMG sends to your application when relevant events occur on your account — for example when a charge is created, completed, refunded, or when a settlement is processed. They let your backend stay synchronised with payment activity without having to poll the Charge or Settlement APIs.
How webhooks work
When an event occurs, DMG sends an HTTP POST to the webhook endpoint URL you've configured in the Merchant Dashboard. The body of the POST contains the event payload (event type, unique identifier, current status, and any relevant references). Your application acknowledges receipt with an HTTP 200 response; non-2xx responses or timeouts trigger the retry policy.
For step-by-step instructions on creating and configuring a webhook subscription, see Creating and Configuring Webhooks.
Webhook types
DMG sends three categories of webhook:
- Charge — fires as a transaction moves through its lifecycle.
- Settlement — fires when a settlement is created, pending, or completed.
- Disbursal — fires as payouts are created and settle to the merchant's bank.
Subscribers select which event types to receive when configuring the webhook in the Merchant Dashboard.
Charge webhook
Lifecycle
A charge moves through the following statuses:
created → pending_authorisation → validated → completed → refunded
(Not every charge reaches every status — for example, a card declined during authorisation moves directly to not_authorised rather than validated. See Charge webhook events for the full state table.)
Recommended handling
At a minimum, capture the completed status — this is the point at which the payment has been successfully processed.
For any charge that reaches completed or refunded, extract the charge_id and call GET /charge/{charge_id} against the Charge API to fetch the full transaction record for reconciliation.
Payload fields
| Field | Type | Description |
|---|---|---|
id | UUID | Unique identifier for this webhook delivery. |
charge_id | UUID | Unique identifier of the charge the event refers to. |
timestamp | Unix timestamp | When the charge event was created. |
order_id | UUID | The order the charge belongs to. |
service_id | UUID | The accounting token of the payment service used. |
amount | Integer | Amount of the charge in the smallest currency unit. |
charge_status.status | String | Current status of the charge (e.g. created, pending_authorisation, completed, refunded). See the full set in Charge webhook events. |
charge_status.timestamp | ISO 8601 | When the status was set. |
payment_instrument_id | UUID | Internal identifier of the payment instrument used. |
payment_instrument_type | String | Instrument type (e.g. card_instrument, wallet_instrument, qr_instrument). |
currency_code | String | ISO 4217 currency code followed by the number of implied decimal places in amount — for example IDR2 means Indonesian rupiah with two implied decimals, so an amount of 10560000 represents 105,600.00. |
object_type | String | Always "webhook.charge". |
version | String | Payload version. |
event | String | Event name (e.g. charge.completed). |
For sample payloads of every charge event type, see Charge webhook payloads.
Settlement webhook
A settlement webhook fires as a settlement transitions through its statuses. Use the settlement_id from the payload to query the Settlement API for the full settlement details.
Payload fields
| Field | Type | Description |
|---|---|---|
id | UUID | Unique identifier for this webhook delivery. |
settlement_id | UUID | Unique identifier of the settlement the event refers to. |
settlement_date | ISO 8601 | The settlement date. |
settlement_status.status | String | One of settled, pending_settlement, settled_out_of_balance, validated. |
settlement_status.timestamp | ISO 8601 | When the status was set. |
object_type | String | Always "webhook.settlement". |
version | String | Payload version. |
event | String | Event name (e.g. settlement.settled). |
For sample payloads of settlement events, see Settlement webhook payloads.
Disbursal webhook
A disbursal webhook fires as funds are released to the merchant's bank account, with statuses created, pending_disbursal, and settled. See Disbursal webhook payloads for sample payloads.
Retries
Webhook delivery follows a documented retry policy with up to 7 attempts on increasing intervals. Your endpoint has 20 seconds to respond with HTTP 200 before a delivery is considered failed.