Razorpay Settlement Delay Sentinel for Kestra

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

Razorpay collects a business's payments and settles them to its bank account, usually two working days later. When a settlement fails because the bank details are wrong, or stops because the account is on hold, nothing pages the business: the finance team finds out days later when the bank balance does not match. This blueprint turns a scheduled, read-only call to the Razorpay Settlements API into a cash-flow gate: io.kestra.plugin.core.http.Request reads recent settlements, one jq query counts processed, failed and stuck settlements and adds up the money that reached the bank, and the result routes to a quiet log or a Slack alert.

How it works

list_settlements (io.kestra.plugin.core.http.Request) calls GET /v1/settlements with from and to covering the last lookback_days (Unix seconds) and count=100, using HTTP basic auth with the Razorpay key ID and key secret. It is a read: nothing is created or changed. Retries cover short network blips, and allowFailed plus allowFailure keep an API error from aborting the flow so it can be reported instead.
summarize_settlements (io.kestra.plugin.core.debug.Return) first guards for a missing or non-200 response (UNREACHABLE). Otherwise one jq query counts settlements by status, marks any still created for longer than max_pending_hours as delayed, adds up the amount of processed settlements (converted from paise to rupees), keeps the UTR of the latest one, and classifies the window: any failed settlement is FAILED, any delayed one is DELAYED, no settlements at all is NONE when expect_settlements is true, otherwise HEALTHY.
route_by_settlement_state (io.kestra.plugin.core.flow.Switch) branches on that classification: HEALTHY logs the settled amount and latest UTR, DELAYED and NONE post a Slack message, FAILED and UNREACHABLE page Slack. A defaults fallback logs anything unexpected.
log_audit_result (io.kestra.plugin.core.log.Log) writes one audit line per run with the HTTP status and the full summary, so the check's own history survives a Slack outage.
The flow-level errors block pages Slack if the flow itself fails, so a broken sentinel is never mistaken for settlements arriving normally.
The morning_check trigger runs at 10:00 IST (04:30 UTC) every day and ships disabled: true.

What you get

A daily, read-only settlement check with no custom scripting and no extra plugin to install.
A status output (HEALTHY / DELAYED / NONE / FAILED / UNREACHABLE) and a settled_rupees output other flows can use, for example to hold a vendor payout run until settlements have landed.
Slack messages that say what went wrong and what to check, not just that something failed.
An audit line on every run with the settled amount and the latest UTR, which the finance team can match against the bank statement.

Who it's for

Indian businesses taking payments through Razorpay whose cash flow depends on settlements arriving on time.
Finance and accounts teams who reconcile Razorpay settlements against the bank statement and want to hear about a failed or held settlement the same morning.
Teams that already run their finance data and alerting in Kestra.

Why orchestrate this with Kestra

Razorpay's Dashboard shows settlement status when someone opens it, and a failed or held settlement is easy to miss in a busy week. Kestra turns a plain, read-only API call into a scheduled, typed classification with retries, a failure path and a full execution history, and the status output lets other flows wait for the money before paying vendors or closing the day's books.

Prerequisites

A Razorpay account. Test mode is free and uses the same API: generate test keys (they start with rzp_test_) in the Dashboard under Account & Settings > API Keys.
A Slack incoming webhook for the DELAYED, NONE, FAILED, UNREACHABLE and flow-failure alerts.

Secrets

RAZORPAY_KEY_ID: the Razorpay API key ID.
RAZORPAY_KEY_SECRET: the matching key secret.
SLACK_WEBHOOK: Slack incoming webhook used for every alert branch and the flow-failure alert.

In Kestra OSS, secrets are supplied as environment variables prefixed SECRET_ and base64-encoded, for example SECRET_RAZORPAY_KEY_ID=$(echo -n 'rzp_test_xxxxxxxx' | base64), and read back with {{ secret('RAZORPAY_KEY_ID') }}. Use the Enterprise secrets backend for encryption at rest and access control.

Quick start

Sign up for Razorpay and generate API keys. Test mode has no real settlements, so to see real data, run against live keys with read-only use in mind; the flow never writes.
Add RAZORPAY_KEY_ID, RAZORPAY_KEY_SECRET and SLACK_WEBHOOK as secrets.
Run the flow manually and check status, settled_rupees and the latest UTR in the logs against the Settlements page in the Razorpay Dashboard.
Set max_pending_hours to match your settlement cycle (for example 48 for T+2, 24 if you use instant settlements) and enable morning_check.

How to extend

Add a Request to GET /v1/settlements/recon/combined to list the payments, refunds and fees inside each settlement for line-by-line reconciliation.
Load the settlements into your warehouse with a JDBC task so the finance team can match UTRs against the bank statement in SQL.
Store the last status in a KV store and alert only when it changes.
Gate a vendor payout flow on status == HEALTHY with a Flow trigger.

Inputs

lookback_days: type INT, default 3.
max_pending_hours: type INT, default 48.
expect_settlements: type BOOL, default true.

Outputs

status: one of HEALTHY, DELAYED, NONE, FAILED, UNREACHABLE.
settled_rupees: total amount of processed settlements in the window, in rupees.
Example path: {{ fromJson(outputs.summarize_settlements.value).latest_utr }} for the bank UTR of the latest settlement.

Pitfalls

count is capped at 100 per call; that covers more than three months of daily settlements, but add paging with skip if you use a much longer window.
Amounts come back in paise; the jq query divides by 100, so settled_rupees is in rupees.
Settlements only happen on working days, so a long weekend or a bank holiday can make NONE fire with a 1-day window; keep lookback_days at 3 or more, or set expect_settlements to false.
This flow only reads; it never creates or changes a settlement, so there is nothing destructive to guard with a dry run.