Configure payout schedules
Change when your merchants' funds are paid out to their verified bank account.
Datman pays out the funds in a merchant's balance to their verified bank account on a payout schedule. The schedule defines when a payout is initiated, for example every weekday at 07:00.
When you change a payout schedule, consider the merchant's settlement delay: the number of days after a payment before its funds are settled. Settlement is usually two business days (T+2). Some merchants get T+1 or T+4, depending on what is agreed when the merchant is onboarded.
Requirements
Before you begin, take into account the following requirements, limitations, and preparations.
| Requirement | Description |
|---|---|
| Integration type | You need a Datman reseller or platform integration. |
| API credentials | You need your api_key, sent in the api_key header. See Authentication. |
| Limitations | You can only change the schedule of merchants that belong to your reseller. The merchant must have a balance account with an active payout schedule. |
How it works
Each merchant with a balance account has one active payout schedule. When the time in the schedule is reached, Datman initiates a payout from the merchant's balance to their bank account.
A payout schedule has the following details:
| Field | Description |
|---|---|
payout_schedule | The schedule in words, for example Every weekday at 7:00 AM. For a schedule that pays out when the balance reaches an amount, it is When balance reaches <value> <currency>. |
cron_expression | The schedule as a 5-field cron expression: minute, hour, day of the month, month, day of the week. For example, 0 7 * * 1-5 is every weekday at 07:00. |
payout_timezone | The timezone of the merchant's balance account, for example Europe/London. |
settlement_delay | The settlement delay in days, as a string. For example, "2" for T+2. |
sweep_id | The ID of the payout schedule. |
Change a payout schedule
To change when a merchant is paid out:
-
Get the merchant's current payout schedule. Make a GET request to Get payout schedule with the merchant's MID in the path.
Note that every field in the response is null when the merchant has no balance account or no active payout schedule. The request does not return an error in this case.
-
Make a POST request to Update payout schedule with the merchant's MID in the path, and the following parameter in the body:
Parameter Required Description cronExpressionRequired The new schedule as a 5-field cron expression (minute hour day-of-month month day-of-week). Textual weekdays such as MON-FRI are accepted. In the following example, Example Pizza Ltd wants its funds paid out every weekday at 07:00.
Pay out every weekday at 07:00
{ "cronExpression": "0 7 * * 1-5" }The API Explorer has the full Update payout schedule request, with examples you can try.
-
The response contains the payout schedule after the update, with the same fields as in step 1.
Response - Schedule updated
{ "data": { "payout_schedule": "Every weekday at 7:00 AM", "payout_timezone": "Europe/London", "settlement_delay": "2", "cron_expression": "0 7 * * 1-5", "sweep_id": "SWPC00000000000000000000001" } }
If the request fails, the response contains an error.code:
| HTTP status | error.code | What to check |
|---|---|---|
| 404 | NOT_FOUND | The merchant doesn't belong to your reseller, or it has no active payout schedule. |
| 422 | VALIDATION_ERROR | The cron expression is missing or isn't a valid 5-field cron expression, or the merchant has no balance account. |
| 502 | UPSTREAM_ERROR | The payout schedule could not be updated. Try again later. |
Track payouts
You can track the payouts of a merchant by listing them:
-
List the payouts of the merchant, with the merchant's MID in the path. Use the
limitquery parameter to set the number of payouts, up to 200. The default is 50.The response contains the most recent payouts, newest first. For each payout, it contains:
total: the payout amount, in major units.status: the status of the payout, for example SENT, PENDING or FAILED.expected_date: the date the payout is expected.payment_provider: the route the payout was sent through.
Note that the list has no paging. Payouts from a merchant's balance account are included only when their status is SENT or FAILED.
Response - Payouts
{ "data": [ { "id": 778899, "total": 1250.75, "status": "SENT", "expected_date": "2026-10-20T00:00:00Z", "sort_date": "2026-10-19T07:00:12Z" } ] } -
To see totals, get the payout statistics of the merchant. The response contains, for each payout status, the number of payouts (
order_count) and the total amount in major units (total_amount), for all time.Note that the statistics only count payouts from the merchant's balance account. Payouts made in batches are not included.