Reconcile transactions
Track your merchants' payments, refunds and splits, and reconcile them with your records.
Here we explain how to track a payment through the Datman transaction APIs, from the list of all your merchants' transactions to the details of one payment.
Payment flow and reporting
-
When a shopper pays one of your merchants, the payment is recorded as a transaction for that merchant's MID. Each transaction has a
status, which changes as the payment moves through its lifecycle. The possible values are: SUCCESS, REFUNDED, DECLINE, RISK-CHECK-DECLINE, FAILED, ERROR, 3DS-PROGRESS, PRE_AUTH, AUTHORISED, CANCELLED and DISPUTES. -
The
transactionTimeindicates when the payment was made. -
The funds are available to the merchant after the settlement delay. This is usually two business days after the payment (T+2), or T+1 or T+4, depending on what is agreed when the merchant is onboarded.
In the example on this page, we follow a GBP 24.50 payment to Example Pizza Ltd, of which GBP 3.50 is a delivery fee split to Example Couriers Ltd.
Track a payment
In this example, we use the following identifiers to track the payment. These identifiers are exchanged in API requests and responses, and are also included in webhooks.
| Identifier | Description |
|---|---|
orderRef | Datman's order reference for the payment. You use it to get the details of a transaction. |
resellerOrderId | Your original order ID, when Datman maps it to its own order reference. |
internalReference | The merchant reference that you sent with the payment. |
xref | Datman's payment reference, in the format O<order_id>M<merchant_id>T<payment_id>. You need it to capture, adjust or reverse a payment. |
Note that the amounts in these APIs are in major units, for example 24.50.
List transactions
To get all transactions for a period, send a List transactions in a date range request with the following parameters:
| Parameter | Required | Description |
|---|---|---|
fromDate | Required | The start date, in YYYY-MM-DD format. |
toDate | Required | The end date, in YYYY-MM-DD format. |
merchantId | Only return transactions of this merchant. | |
status | Only return transactions with these statuses. To filter on refunded transactions, use REFUND. | |
timezone | The timezone of the dates and of the returned timestamps. The default is Europe/London. | |
limit | The number of transactions per page, up to 50. The default is 25. | |
cursor | The pagination.nextCursor from the previous page. |
The API Explorer has the full request, with examples you can try.
The response contains the transactions, newest first. When pagination.hasMore is true, send the pagination.nextCursor as cursor to get the next page. For each transaction, the response contains the amount, the net amount, the fees deducted (deductions), and the fee Datman charges the merchant (datman_fee).
Response - One transaction (trimmed)
{
"data": {
"transactions": [
{
"id": "p_100231",
"transactionTime": "2026-10-14 13:45:12",
"orderRef": "987654321",
"amount": 24.5,
"currencyCode": "GBP",
"status": "SUCCESS",
"merchantId": 1000001,
"merchantName": "Example Pizza Ltd",
"resellerOrderId": "ORD-100245",
"internalReference": "ORD-100245",
"net": 23.9,
"deductions": 0.6,
"datman_fee": 0.6
}
],
"timezone": "Europe/London"
},
"pagination": { "hasMore": false, "nextCursor": null }
}Find a transaction
If you know an identifier of the payment, you can search for it instead:
- Search transactions by order identifier, with the value in
query. UsesearchByto choose whatqueryis matched against: orderId (default), merchantReference, resellerOrderId or merchantId.
Get the details of a transaction
To see the full history of the payment, get the full details of the transaction, with the orderRef in the path. The response contains:
transactions: every payment recorded under the order reference.refunds: the refunds of the payment.chargebacks: the chargebacks of the payment.splits: the shares of the payment that were booked to other merchants.shopper: the shopper's details.
Note that the keys in this response are in snake_case, for example order_ref, and that amounts can be returned as strings, such as "24.5000". Parse them as numbers. Pass the timezone query parameter to get timestamps in the YYYY-MM-DD HH:MM:SS format in that timezone.
You can also get parts of the transaction separately:
| Task | API reference |
|---|---|
| Get the split breakdown | Get the revenue split breakdown for a transaction. In our example, it returns GBP 3.50 for Example Couriers Ltd, and how much of it has been refunded in amount_refunded. |
| Get the refunds | Get refunds recorded against a transaction, with source payments and the orderRef. Each refund has an amount and a time. |
Check webhook deliveries
To check which webhooks Datman sent for a payment, get the webhook deliveries for the transaction, with the numeric payment ID in the path. This is the transaction id without the p_ prefix, for example 100231.
For each webhook, the response contains the webhook_url that was called, the action, the payload, the http_response_code your server returned, and when it was sent (created_at).
Recommendations
We recommend that you use the payment status webhook to track individual payments and update your ledger as each one changes. That gives you the most up-to-date status of each payment. You can then reconcile the payments of all your merchants daily, by listing the transactions for the previous day.