Version: 3.2.0

API Integration

Two APIs are available for merchants to retrieve the settlement information.

Settlement Header API: The merchant can specify the settlement Id or give a date range

Transaction API: a page/subset of transactions in a settlement will be return based on the offset and limit parameter passed in

All Production API access is via

India Environment: https://api.in.dmgsecure.io
Australia Environment: https://api.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.

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 DMG’s account token, also known as an entity ID.
`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": null,
          "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
      }
  ]
}

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

Below transaction details are listed in the response.

note

Transaction 1 is the example of EIPP and Virtual Account extra fields.

Transaction 2 is the example of MarketPlace (2 sellers) and Virtual Account extra fields.

Transaction 3 is the example of Hosted Payment Page (HPP).

Key	Description
`merchantId`	String Merchant ID in UUID format.
`chargeId`	String Charge ID in UUID format.
`transactionId`	String Transaction ID in UUID format.
`timestamp`	String ISO 8601 format
`transactionType`	String
`paymentType`	Number
`amount`	Number Transaction amount in the smallest unit of the currency. Example: 2300000
`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.
`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).
`currencyCode`	Number The currency code used in Settlement in ISO 4217 format.
`state`	String The state of the order Example: Approved
`orderId`	String Order ID in UUID format.
`notes`	Array Extra data from HPP (old version) - TBC.. VA, EIPP, HPP in new version

{
 "status": {
    "code": "0",
    "response": "Success"
 },
 "data": [
   {
   // *** Standard Transaction Information *** //
      "chargeId": "faff4148-e449-47a2-b487-863b7126a46d",
      "transactionId": "b8a549a9ac864a53907f204855fb745401",
      "timestamp": "20231026044834",
      "transactionType": "Purchase Transaction",
      "paymentType": "card_instrument",
      "amount": "15000",
      "fees": "40",
      "tax": "4",
      "state": "Approved",
      "order_id": "",
      "notes": [

      ] // END payment_information
     }
    ]
 }
}

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

Settlement Header Details API​

Request​

Response​

200 - OK​

200 - Error​

Transaction Details API​

Request​

Response​

200 - OK​

200 - Error​

Settlement Header Details API

Request

Response

200 - OK

200 - Error

Transaction Details API

Request

Response

200 - OK

200 - Error