Version: 4.0.2

API Integration

Three APIs are available for merchants to retrieve and interact with settlement information.

Settlement Header API: The merchant can specify the settlement Id or give a date range to retrieve settlement header information.

Transaction API: A page/subset of transactions in a settlement will be returned based on the offset and limit parameters passed in.

Settlement Webhook: Real-time notifications are sent when settlement events occur, allowing merchants to take immediate action.

All Production API access is via

India Environment: https://api.in.dmgsecure.io
Australia Environment: https://api.datameshgroup.io
Korea Environment: https://api.kr.datameshgroup.io

This is our primary environment.

You may also be given access to our Staging environment. If this is the case, the access URL will be different.

Staging Environment: https://api.in.stg.dmgsecure.io/

API Response Wrapper

Both settlement header and transactions API responses are returned in the settlement wrapper data structure.

Schema

Field	Type	Description
`status`	object	code (string) - the result code of the request response (string) - Status can be either Success, Fail, or other information Example: {"code": "0","response": "Success" }
`data`	array	The settlement header or transactions payload

Status codes

Code	Meaning
`0`	Success
`429`	Rate limit exceeded
`1000`	General exception
`1001`	Access denied
`1002`	Auth token missing or invalid
`1010`	Not implemented
`1020`	Missing required parameters
`2001`	Database read error

Settlement Webhook

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.

Webhook Payload Structure

Schema
Sample

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.

{
  "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"
}

For more details on setting up and handling webhooks, see the Completion Notification documentation.

Settlement Header Details API

Request

Merchants can submit requests with parameters such as Date Range (startDate, endDate), and authentication credentials.

If startDate and endDate are specified, then the settlements with settlement date between the date range will be returned. e.g. if settlements on 3/Mar/2024, 4/Mar/2024 and 5/Mar/2024 will be returned if the value of startDate and endDate is "2024-03-03" and "2024-03-05" respectively.

POST /v1/merchant/settlement

note

Required Scopes: read:merchant, read:merchant:settlement

Parameters

Field ID	Description
`settlementId` Optional	String This is to retrieve a specific Settlement. Format UUID/String
`cid` Optional	Int Company ID as optional for filtering.
`chid` Optional	Int Chain ID as optional for filtering.
`mid` Optional	String The Merchant ID. Format UUID/String
`startDate` Optional	String The from_date denote the starting date for which multiple settlement data is to be included in the report. Format YYYY-MM-DD
`endDate` Optional	String The End Date of the date range filter to determine the oldest date a settlement has been created. Format YYYY-MM-DD
`limit` Optional	Number Number of settlements to show per query, default is 50
`offset` Optional	Number The number of records to offset by, default is 0

Sample request

{
  "settlementId": "xxxx",
  "cid": 1,
  "chid": 2,
  "mid": "xxxx",
  "startDate": "2023-09-02",
  "endDate": "2024-12-03",
  "limit": 1,
  "offset": 1
}

Response

200 - OK

Settlement header details are returned.

Schema
Sample

Status

Key	Description
`code`	String the result code of the request
`response`	String Status can be either Success, Fail, or other information

Data

Key	Description
`settlementId`	String Settlement ID
`paymentService`	String The payment service used to obtain this data.
`merchantId`	String DMG's merchant ID.
`accountingToken`	String The accounting token of the payment service the settlement belongs to, also known as an entity ID. This is the same value delivered as `service_id` in charge webhooks — use it to attribute settlements to the correct entity when reconciling in your finance or ERP systems, particularly if you operate multiple legal entities or payment services under one merchant.
`settlementStatus`	String Status of the settlement, this can be settled, pending_settlement or settled_out_of_balance.
`settlementDate`	String Date and time of the settlement report was provided for this record, in ISO 8601 format.
`amountGross`	Number Gross settlement amount exclusive of tax in the smallest unit of the currency.
`fees`	Number Fees associated to the settlement in the smallest unit of the currency.
`tax`	Number Tax associated to the settlement in the smallest unit of the currency.
`currencyCode`	String The currency code used in Settlement in ISO 4217 format.
`amountPayIn`	Number Amount to be paid into the settlement account in the smallest unit of the currency.
`decimalPlaces`	Number decimal places used in order to bring to more common unit, e.g. 2 would equal 100 sub-units (e.g. cents, pence etc).
`paymentEndToEndIds`	String[] Array of EndtoEndIDs value from the PAIN001 file provided at settlement processing.
`paymentReferences`	String[] Array of PmtInfIDs value from the PAIN001 file provided at settlement processing.
`totalTransactions`	Number Total number of transactions for this settlement report.

{
  "status": {
      "code": "0",
      "response": "Success"
  },
  "data": [
      {
          "settlementId": "e3c09089-b68d-4592-a36a-a443eaa7f9b3",
          "paymentService": "Stream 2",
          "merchantId": "c94648f5-bd1a-4b48-9e32-bf6f49fb7c54",
          "accountingToken": "67e594aa-6b45-4613-8764-f88cfc7654cd",
          "settlementStatus": "settled",
          "settlementDate": "2024-06-13T03:08:00.000Z",
          "amountGross": 300000,
          "fees": 6600,
          "tax": 1188,
          "currencyCode": "INR",
          "amountPayIn": 300000,
          "decimalPlaces": "2",
          "paymentEndToEndIds": [ "id1", ... ],
          "paymentReferences": [ "id1", ... ],
          "totalTransactions": 1
      }
  ]
}

Settlement Status Types

The settlementStatus field in the response can have the following values:

Status	Description
`settled`	The settlement has been successfully processed and funds have been transferred.
`pending_settlement`	The settlement is in progress but not yet complete.
`settled_out_of_balance`	The settlement has been processed but there is a discrepancy between the expected and actual amounts.
`validated`	The settlement has been validated but not yet processed.

200 - Error

Settlement header details are returned.

Schema
Sample

Status

Key	Description
`code`	String The result code of the request
`response`	String Status should be the error type.
`message`	String The error message provided back from the API

{
  "status": {
      "code": "1020",
      "response": "Missing input params",
      "message": "startDate is supplied but is invalid"
  }
}

Transaction Details API

Request

Merchants can submit requests with parameters such as settlementId, offset and limit (optional) to retrieve a subset of transactions in a settlement.

POST /v1/merchant/settlement/transactions

note

Required Scopes: read:merchant, read:merchant:settlement

Parameters

Field ID	Description
`settlementId`	String The Unique Identifier of a Settlement. When this settlementIdpassed in the request, the transactions linked to this settlement will be returned.
`limit` Optional	Number The limit parameter controls the maximum number of items that may be returned for a single request. If no limit is specified, the system defaults to a limit of a default value. The maximum valid limit value is 100 which could vary depending on the solution capacity. Default value is 50
`offset` Optional	Number The offset parameter controls the starting point within the collection of resource results. Note that the first item in the collection is retrieved by setting to 0. Default value is 0

Sample request

{
  "settlementId": "8f33a85b-bc5e-4ca8-ac66-caa1a6202c3b",
  "limit": 10,
  "offset": 1
}

Response

200 - OK

The response format includes structured settlement data and contain information including transaction details, settlement amounts, and timestamps.

Schema
Sample

Status

Key	Description
`code`	String the result code of the request
`response`	String Status can be either Success, Fail, or other information

Data

Each entry in data is a transaction included in the settlement batch.

Key	Description
`chargeId`	String Charge ID in UUID format.
`transactionId`	String Transaction ID in UUID format.
`timestamp`	String ISO 8601 format
`transactionType`	String Type of transaction (e.g., "Purchase Transaction")
`paymentType`	String Type of payment method used (e.g., "Card Payment").
`amount`	Number Transaction amount in the smallest unit of the currency.
`fees`	Number Fees associated to the transaction in the smallest unit of the currency.
`tax`	Number Tax associated to the fees in the smallest unit of the currency.
`decimalPlaces`	String Decimal places used to interpret monetary amounts. For example, `2` means the amount is in sub-units (e.g. cents, pence).
`currencyCode`	String The currency of the transaction in ISO 4217 format.
`state`	String The state of the transaction (e.g., "Approved").
`orderId`	String Order ID in UUID format.
`notes`	Array of `{key, value}` objects Merchant-defined key-value pairs captured against this transaction. Used to carry merchant references (e.g. `merchant_order_ref`, `merchant_customer_ref`) for reconciliation; not used operationally by DMG.
`settlementId`	String The settlement batch UUID this transaction belongs to.

{
"status": {
  "code": "0",
  "response": "Success"
},
"data": [
  {
    "chargeId": "cda01b96-30ef-4185-823a-e9cfcd921d78",
    "transactionId": "cda01b96-30ef-4185-823a-e9cfcd921d78",
    "timestamp": "2025-05-13T18:36:19.000Z",
    "transactionType": "Purchase Transaction",
    "paymentType": "Card Payment",
    "amount": 12429900,
    "fees": 285900,
    "tax": 28600,
    "decimalPlaces": "2",
    "currencyCode": "KRW",
    "state": "Approved",
    "orderId": "304bbf25-d164-403e-ad15-98f4f1e16ab7",
    "notes": [
      { "key": "merchant_order_ref", "value": "your-order-123" },
      { "key": "merchant_customer_ref", "value": "customer-456" }
    ],
    "settlementId": "5c8eebd5-b67c-4be4-84fd-f6d16f4d74fb"
  }
]
}

200 - Error

Settlement header details are returned.

Schema
Sample

Status

Key	Description
`code`	String the result code of the request
`response`	String Status should be the error type.
`message`	String The error message provided back from the API

{
  "status": {
      "code": "1020",
      "response": "Missing input params",
      "message": "startDate is supplied but is invalid"
  }
}

API Response Wrapper​

Status codes​

Settlement Webhook​

Webhook Payload Structure​

Settlement Header Details API​

Request​

Response​

200 - OK​

Settlement Status Types​

200 - Error​

Transaction Details API​

Request​

Response​

200 - OK​

200 - Error​

API Response Wrapper

Status codes

Settlement Webhook

Webhook Payload Structure

Settlement Header Details API

Request

Response

200 - OK

Settlement Status Types

200 - Error

Transaction Details API

Request

Response

200 - OK

200 - Error