Notification When Settlement Completes

The acknowledgement of settlements have been completed are provided in real-time using webhooks, then to get further information of the settlement data, we can use the API endpoints in the following sections.

Webhooks are automated messages sent from DMG systems when an event happens. They are a way for an app to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately. Webhooks are commonly used to automate workflows and integrate different services.

In the context of this system, webhooks notify merchants about specific settlement events, such as after the processing of settlements has occurred. When such an event occurs, the webhook sends an HTTP POST request to a specified URL with a payload containing the event data.

Webhook Payload Structure

A settlement webhook will fire to your application as the status changes in a settlement. The status is defined by the settlement_status.status field.

You can choose which statuses should trigger a webhook call to your application. This can be configured in the Merchant Portal.

Payload Fields

Field	Type	Description
id	UUID	Unique ID for this webhook payload.
settlement_id	UUID	Unique ID for the settlement.
settlement_date	ISO 8601	Time of the settlement.
settlement_status.status	string	The status of the settlement. One of: settled, pending_settlement, settled_out_of_balance, validated
settlement_status.timestamp	ISO 8601	Time when the status was updated.
object_type	string	Set to "webhook.settlement"
version	string	Version of the webhook payload format.
event	string	Type of event that triggered the webhook.

Example Payload

{
    "id": "641f615d-29fd-4b46-8e3e-60464aeaaddb",
    "settlement_id": "ab9968a6-0596-4207-81c3-cb848f7b9127",
    "settlement_date": "2025-02-24T01:26:45Z",
    "settlement_status": {
        "status": "settled",
        "timestamp": "2025-02-24T01:26:45Z"
    },
    "object_type": "webhook.settlement",
    "version": "1.2.0",
    "event": "settlement.settled"
}

How to Implement Webhooks in Your Code

Implementing webhooks involves two main steps: setting up a server to receive the webhook data and handling the incoming data. For simplicity sake, we will just focus on the code to show the event details in the console log, we'll leave you to discuss with your system integrator on the exact logic required for your business.

You need to set up a server that can receive HTTP POST requests. Here's an example using Node.js and Express.

// Import required modules
const express = require('express');
const bodyParser = require('body-parser');
const app = express();
const port = 3000;
// Middleware to parse JSON bodies
app.use(bodyParser.json());
// Define a route to receive webhooks
app.post('/webhook', (req, res) => {
    const event = req.body;
    // Log the received event data
    console.log('Received webhook event:', event);
    // Handle the event (e.g., store it in a database, trigger other actions)
    // ...
    // Respond to acknowledge receipt of the webhook
    res.status(200).send('Webhook received');
});
// Start the server
app.listen(port, () => {
    console.log(`Server listening at http://localhost:${port}`);
});

Setting up Settlement Webhooks

To set up Settlement Webhooks:

1. Log into the Merchant Dashboard.

2. Click on Webhooks.

3. Add a new webhook by clicking on Add Webhook (Note: You can also edit an existing webhook to include Settlement Webhooks. For simplicity, we will refer to creating a new webhook.)

4. In the Webhook Name field, give the webhook a name. We recommend using the name of the system and general webhooks for ease of reference.

5. Add the intended URL location in the Webhook Endpoint field to let DMG know where to send the POST request. In our case, we will use https://acme.com/webhook/

6. Click on Webhook Events. This will display a list of events that can be selected. For our purposes, select "Settled," "Settled Out Of Balance," and "Pending Settlement."

7. Enter a description of the webhook in the Webhook Description field. This can be left blank.

8. Enter the authentication details under the Authentication section. This is for HTTP AUTH (authentication prompt) set onto the destination URL in the Webhook Endpoint. Note that anything conforming to validation can be entered, and the endpoint doesn't require this.

9. Click Save, which should direct you back to the webhook listing.

10. Ensure the webhook Status is set to "On".

Now, wait for the next settlement to arrive, which normally happens every bank workday, depending on the bank and location.

Handling Different Settlement Status Events

The webhook payload includes a settlement_status.status field that indicates the current status of the settlement. You should handle each status appropriately in your application:

• settled: The settlement has been successfully processed and funds have been transferred. You can update your records to reflect the completed settlement.

• pending_settlement: The settlement is in progress but not yet complete. You might want to mark this settlement as pending in your system.

• settled_out_of_balance: The settlement has been processed but there is a discrepancy between the expected and actual amounts. This may require manual investigation.

• validated: The settlement has been validated but not yet processed. This is an intermediate state before the settlement is processed.

When you receive a webhook notification, you can use the settlement_id to retrieve more detailed information about the settlement using the Settlement Header API and Transaction API described in the API Integration documentation.