Ledger balances
Balance monitoring
Get a webhook when a balance crosses a threshold you set.
A balance monitor watches one amount on a balance, such as what it holds or what it has sent. Blnk sends you a webhook when that amount crosses a threshold you set.
Use it for a low balance, a spending cap, or money on hold past a limit. You choose the threshold, and whether the webhook arrives once or on every update while the amount stays past it.
How monitors work
You set trigger to edge or level. That choice decides how often Blnk sends the balance.monitor webhook.
| Trigger | When Blnk notifies you |
|---|---|
edge | Once, the first time your rule matches. Quiet until the amount no longer matches, then again on the next match. |
level | On every transaction that updates the balance while your rule still matches. |
A monitor on balance matches when the balance is below 100.00. As transactions land, the two triggers notify you like this:
| Balance | edge | level |
|---|---|---|
| 150.00 | No webhook | No webhook |
| 80.00 | Webhook | Webhook |
| 60.00 | No webhook | Webhook |
| 120.00 | No webhook | No webhook |
| 90.00 | Webhook | Webhook |
Create a monitor
To create a new monitor, call Create balance monitor.
This example watches debit_balance (the total the balance has sent), and notifies you once when that total goes above 1,000.00.
Write value in the currency’s normal units, and set precision to the scale you already use for that currency. 1000 at precision 100 is 1,000.00.
curl -X POST "http://localhost:5001/balance-monitors" \
-H "X-blnk-key: <api-key>" \
-H "Content-Type: application/json" \
-d '{
"balance_id": "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
"trigger": "edge",
"condition": {
"field": "debit_balance",
"operator": ">",
"value": 1000,
"precision": 100
},
"description": "Spending above 1000"
}'const response = await blnk.BalanceMonitor.create({
balance_id: 'bln_0be360ca-86fe-457d-be43-daa3f966d8f0',
condition: {
field: 'debit_balance',
operator: '>',
value: 1000,
precision: 100,
},
description: 'Spending above 1000',
});monitor, _, _ := client.BalanceMonitor.Create(blnkgo.MonitorData{
BalanceID: "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
Condition: blnkgo.MonitorCondition{
Field: "debit_balance",
Operator: blnkgo.OperatorGreaterThan,
Value: 1000,
Precision: 100,
},
Description: "Spending above 1000",
})response = blnk.balance_monitor.create({
"balance_id": "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
"condition": {
"field": "debit_balance",
"operator": ">",
"value": 1000,
"precision": 100,
},
"description": "Spending above 1000",
})ApiResponse<JsonNode> response = blnk.balanceMonitor().create(
MonitorData.create()
.balanceId("bln_0be360ca-86fe-457d-be43-daa3f966d8f0")
.condition(MonitorCondition.create()
.field("debit_balance")
.operator(">")
.value(1000)
.precision(100))
.description("Spending above 1000"));| Field | Description | Required |
|---|---|---|
balance_id | Balance to watch. | Yes |
condition | The amount, the comparison, the threshold, and the precision. | Yes |
field | Which amount. balance is what it holds now. credit_balance is the total received. debit_balance is the total sent. inflight_balance, inflight_credit_balance, and inflight_debit_balance are amounts still on hold. See Balances overview. | Yes |
operator | How to compare the amount with the threshold. See Operators. | Yes |
value | Threshold in the currency. 0 and amounts such as 100.50 are valid. | Yes |
precision | Scale for value, the same one you use when you record that currency. Greater than 0. | Yes |
trigger | edge or level. Leave it out on 0.15.7 and the monitor notifies you once per crossing. | No |
description | A label for the monitor. Empty when you leave it out. | No |
{
"monitor_id": "mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0",
"balance_id": "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
"condition": {
"field": "debit_balance",
"operator": ">",
"value": 1000,
"precision": 100,
"precise_value": 100000
},
"description": "Spending above 1000",
"trigger": "edge",
"condition_state": false,
"created_at": "2024-02-20T05:56:58.257315054Z"
}
| Field | Description |
|---|---|
monitor_id | Id of the monitor. Save it to view, update, or delete the monitor. |
precise_value | The same threshold in the currency’s smallest unit. Here, 1,000.00 is 100000. |
trigger | edge or level. |
condition_state | Whether your rule matches right now. An edge monitor includes this. |
description | The label on the monitor. |
created_at | When the monitor was created. |
When a monitor fires, Blnk sends a balance.monitor event to your global webhook URL. data is the monitor that fired, so you can tell which rule matched and on which balance.
{
"event": "balance.monitor",
"data": {
"monitor_id": "mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0",
"balance_id": "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
"description": "Spending above 1000",
"created_at": "2024-02-20T05:56:58.257315054Z",
"condition": {
"field": "debit_balance",
"operator": ">",
"value": 1000,
"precision": 100,
"precise_value": 100000
},
"trigger": "edge",
"condition_state": true
}
}
| Field | Description |
|---|---|
event | Always balance.monitor. |
data.monitor_id | Id of the monitor that fired. |
data.balance_id | Balance whose update matched the rule. |
data.description | The label on the monitor. Left out when the monitor has none. |
data.condition | The rule that matched: the field, operator, and threshold you set. precise_value is the threshold in the currency’s smallest unit. |
data.trigger | edge or level. |
data.condition_state | true on an edge monitor, because Blnk only sends when the rule starts to match. Don’t rely on it for a level monitor. |
data.created_at | When the monitor was created. |
The payload describes the monitor, not the balance. To see the amount that crossed the threshold, call Get balance with data.balance_id.
Blnk signs the request like every other webhook. See Webhook security to verify it.
Supported operators
A symbol outside this list returns 400 GEN_VALIDATION_ERROR.
| Operator | Symbol | Description |
|---|---|---|
| Greater than | > | The amount is above the threshold. |
| Less than | < | The amount is below the threshold. |
| Greater than or equal to | >= | The amount is at or above the threshold. |
| Less than or equal to | <= | The amount is at or below the threshold. |
| Equal to | = | The amount matches the threshold. |
| Not equal to | != | The amount is different from the threshold. |