id: razorpay-settlement-delay-sentinel
namespace: company.team
description: |
Every morning, read recent settlements from the Razorpay API (read-only:
nothing is created or changed) and classify them as HEALTHY, DELAYED,
FAILED, NONE or UNREACHABLE. Log quiet runs and alert Slack when a
settlement to the bank has failed, is stuck for too long, or has not
arrived at all.
inputs:
- id: lookback_days
type: INT
defaults: 3
displayName: "Lookback Window (days)"
description: "How many days of settlements to read on each run."
- id: max_pending_hours
type: INT
defaults: 48
displayName: "Maximum Pending Hours"
description: "A settlement still in the created state for longer than this is
classified DELAYED."
- id: expect_settlements
type: BOOL
defaults: true
displayName: "Expect Settlements"
description: "If true, a window with no settlements at all is classified NONE
and alerted, because a business taking payments every day normally gets
settled every working day."
variables:
api_base: https://api.razorpay.com/v1
triggers:
- id: morning_check
type: io.kestra.plugin.core.trigger.Schedule
description: Check settlements every morning at 10:00 IST, after Razorpay's
usual settlement runs. Shipped disabled; enable it once the Razorpay key
secrets are set and a manual run has been verified.
cron: "30 4 * * *"
disabled: true
tasks:
- id: list_settlements
type: io.kestra.plugin.core.http.Request
description: Read up to 100 settlements created in the lookback window from the
Razorpay Settlements API. This is a GET; nothing is created or changed.
uri: "{{ vars.api_base }}/settlements?count=100&from={{ now() |
dateAdd(-inputs.lookback_days, 'DAYS') | timestamp }}&to={{ now() |
timestamp }}"
method: GET
options:
auth:
type: BASIC
username: "{{ secret('RAZORPAY_KEY_ID') }}"
password: "{{ secret('RAZORPAY_KEY_SECRET') }}"
allowFailed: true
timeout:
connectTimeout: PT10S
readIdleTimeout: PT30S
retry:
type: constant
interval: PT10S
maxAttempts: 3
allowFailure: true
- id: summarize_settlements
type: io.kestra.plugin.core.debug.Return
description: Count processed, failed and still-pending settlements, add up the
amount that reached the bank, flag pending settlements older than the
allowed delay, and classify the window in one jq query. A missing or
non-200 response becomes UNREACHABLE instead of looking healthy.
format: >-
{{ (outputs.list_settlements.code is not defined or
outputs.list_settlements.code != 200) ?
'{"status":"UNREACHABLE","total":0,"processed":0,"failed":0,"delayed":0,"settled_rupees":0,"latest_utr":"none"}'
: (fromJson(outputs.list_settlements.body) | jq(' .items as $s | ([$s[] |
select(.status == "processed")]) as $p | ([$s[] | select(.status ==
"failed")] | length) as $f | ([$s[] | select(.status == "created" and
.created_at < ' ~ (now() | dateAdd(-inputs.max_pending_hours, 'HOURS') |
timestamp) ~ ')] | length) as $d | {total: ($s | length), processed: ($p |
length), failed: $f, delayed: $d, settled_rupees: (([$p[].amount] | add //
0) / 100), latest_utr: (($p | sort_by(.created_at) | last | .utr) //
"none"), status: (if $f > 0 then "FAILED" elif $d > 0 then "DELAYED" elif
($s | length) == 0 and ' ~ inputs.expect_settlements ~ ' then "NONE" else
"HEALTHY" end)} ') | first | toJson) }}
- id: route_by_settlement_state
type: io.kestra.plugin.core.flow.Switch
description: Route to a quiet log when settlements are arriving normally, a
Slack message when one is stuck or none arrived, or a Slack page when a
settlement failed or Razorpay could not be read.
value: "{{ fromJson(outputs.summarize_settlements.value).status }}"
cases:
"HEALTHY":
- id: log_healthy
type: io.kestra.plugin.core.log.Log
message: "Razorpay settlements healthy: {{
fromJson(outputs.summarize_settlements.value).processed }} processed
in the last {{ inputs.lookback_days }} day(s), Rs {{
fromJson(outputs.summarize_settlements.value).settled_rupees }}
settled, latest UTR {{
fromJson(outputs.summarize_settlements.value).latest_utr }}."
"DELAYED":
- id: alert_delayed_settlement
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Post a Slack message when at least one settlement has been pending
for longer than the allowed delay.
url: "{{ secret('SLACK_WEBHOOK') }}"
payload: |
{
"text": "Razorpay settlement DELAYED: {{ fromJson(outputs.summarize_settlements.value).delayed }} settlement(s) still pending after more than {{ inputs.max_pending_hours }} hours. Money from these payments has not reached the bank yet; check the Razorpay Dashboard or raise a support ticket. Execution {{ execution.id }}."
}
"NONE":
- id: alert_no_settlement
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Post a Slack message when no settlement at all was created in the
lookback window, which can mean settlements are on hold.
url: "{{ secret('SLACK_WEBHOOK') }}"
payload: |
{
"text": "Razorpay settlement NONE: no settlement was created in the last {{ inputs.lookback_days }} day(s). If you took payments in that time, settlements may be on hold (for example pending KYC or a risk review). Execution {{ execution.id }}."
}
"FAILED":
- id: alert_failed_settlement
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Page Slack when a settlement failed, which usually means the bank
account details are wrong or the account is frozen.
url: "{{ secret('SLACK_WEBHOOK') }}"
payload: |
{
"text": "Razorpay settlement FAILED: {{ fromJson(outputs.summarize_settlements.value).failed }} settlement(s) failed in the last {{ inputs.lookback_days }} day(s). The money did not reach the bank; check the settlement bank account in the Razorpay Dashboard today. Execution {{ execution.id }}."
}
"UNREACHABLE":
- id: alert_unreachable_api
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Page Slack when the Settlements API could not be read, indicating
an outage, a network problem or invalid API keys.
url: "{{ secret('SLACK_WEBHOOK') }}"
payload: |
{
"text": "Razorpay settlement sentinel UNREACHABLE: the Settlements API did not return a usable response (HTTP {{ outputs.list_settlements.code ?? 'no response' }}). Check the API keys and Razorpay status. Execution {{ execution.id }}."
}
defaults:
- id: log_unclassified
type: io.kestra.plugin.core.log.Log
message: "Razorpay settlement sentinel completed with an unexpected
classification: {{ outputs.summarize_settlements.value }}."
- id: log_audit_result
type: io.kestra.plugin.core.log.Log
description: Record one audit line for every run, whichever branch fired, so the
settlement history stays queryable even if Slack delivery fails.
message: "Razorpay settlement sentinel audit: lookback_days={{
inputs.lookback_days }} http={{ outputs.list_settlements.code ?? 'n/a' }}
summary={{ outputs.summarize_settlements.value }} execution={{
execution.id }}."
errors:
- id: alert_flow_failure
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Alert Slack when the sentinel flow itself fails, so a broken check
is never mistaken for settlements arriving normally.
url: "{{ secret('SLACK_WEBHOOK') }}"
payload: |
{
"text": "Razorpay settlement sentinel flow {{ flow.id }} FAILED (execution {{ execution.id }}). Settlement status is now unknown; check the task logs and the Razorpay Dashboard."
}
outputs:
- id: status
type: STRING
value: "{{ fromJson(outputs.summarize_settlements.value).status }}"
- id: settled_rupees
type: STRING
value: "{{ fromJson(outputs.summarize_settlements.value).settled_rupees }}"