SRS: UC_9.8 — Flow 30: MID Capacity Warning

UC Index

<a id="UC_9.8"></a>

UC_9.8 — Flow 30: MID Capacity Warning

1. Overview

2. Trigger

Type: Internal — fired programmatically by Middleware Hub immediately after Process Payment Webhook successfully updates current_mtd_volume in the database.

Trigger condition: Every successful payment from any gateway (NMI, Triple-A, Nomupay, EBANX, Dusupay, Skrill) and every refund results in a call to POST /merchant/check-capacity for the MID used.

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Check MID Capacity lines 1455–1459; §Process Payment Webhook lines 1339–1346)

3. Basic Flow

Step 1 — Volume Update (upstream — Process Payment Webhook)

After a successful payment, Process Payment Webhook updates the MID's running total in Merchant_Routing_Config:

current_mtd_volume = current_mtd_volume + transaction_amount

On a refund, the MID's running total is decremented and never drops below 0 (e.g. a prior month's transaction refunded right after the 1st-of-month reset):

current_mtd_volume = GREATEST(0, current_mtd_volume - refund_amount)

current_mtd_volume is only an internal month-to-date counter used for load balancing — it is not the merchant bank balance. The refund itself is processed by NMI normally even when current_mtd_volume = 0.

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Process Payment Webhook line 1345; QnA_BACKGROUND_MECHANISMS_CRON.md [BG-024] — client answer 2026-11-03)

Step 2 — Capacity Check (POST /merchant/check-capacity)

Immediately after the DB update, Middleware calls POST /merchant/check-capacity internally.

Input payload:

{
  "merchant_name": "<MID identifier>",
  "current_mtd_volume": <updated value>
}

Evaluation logic:

ratio = current_mtd_volume / monthly_limit

IF ratio >= 0.80 AND warning_80_fired = FALSE:
  → SET warning_80_fired = TRUE
  → FIRE webhook
ELSE IF ratio < 0.80 AND warning_80_fired = TRUE:
  → SET warning_80_fired = FALSE   (no Slack alert)
ELSE:
  → No action. Return HTTP 200.

The warning_80_fired flag makes the 80% alert fire only once per crossing: while it is set, further transactions on the same MID do not re-trigger the flow even if ratio climbs above 90% or 100%. If volume drops back below 80% (a refund, or an increased monthly_limit), the flag is cleared and the next crossing fires a new alert. No separate database trigger or watcher is built — this all happens inside this check.

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Check MID Capacity lines 1456–1459; QnA_BACKGROUND_MECHANISMS_CRON.md [BG-025] — client answer 2026-11-03)

Response: HTTP 200 OK in all cases (fire or no-fire).

Step 3 — Slack Alert

Send a Slack message to the Operations channel (#ops-treasury or configured Ops channel).

Slack message content:

⚠️ [WARN] MID VOLUME CAPACITY ALERT
MID [merchant_name] has reached [ratio]% of its monthly processing limit.
Current MTD Volume: $[current_mtd_volume]
Monthly Limit: $[monthly_limit]
Action Required: Contact processor to request limit increase, or adjust
Weighted Round-Robin weights in Merchant_Routing_Config to offload traffic.

(Source: Zapier Integration V7.pdf §Flow 30 lines 2466–2469)

4. Data Model

Merchant_Routing_Config table (PostgreSQL)

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Merchant_Routing_Config lines 847–855; §Alerting line 3273; client confirmed 2026-09-18)

5. API Endpoints

Input:

Output: HTTP 200 OK (no body required — side effect only)

(Source: RFQ_ Stack Trading Prop Tech V7.pdf §Check MID Capacity lines 1455–1459)

6. Exception Flows

Exc-1 — warning_80_fired already TRUE (duplicate suppression):

• No webhook fired. HTTP 200 returned silently.
• This is expected behavior — the flag is reset by the 1st-of-month cron, or by the next capacity check that finds volume below 80% (see §7).

Exc-2 — MID monthly_limit is NULL or zero:

Middleware MUST apply a guard clause: if monthly_limit IS NULL OR monthly_limit = 0, skip the 80% capacity calculation for that MID, log a server-side warning code NULL_OR_ZERO_MONTHLY_LIMIT_WARNING, and return HTTP 200 (no 500 exception). Additionally, Middleware MUST dispatch an active Ops alert to the #ops-treasury Slack channel with the message:

⚠️ Configuration Error: MID [merchant_name] has an active status but a zero or null monthly limit.

Rationale: a NULL or zero limit on an active MID is a critical configuration error — it must be routed to the Ops team for immediate database correction. This is an internal configuration alert and MUST NOT be routed to Freshdesk.

(Source: client confirmed 2026-09-18)

Exc-3 — Webhook delivery fails:

When Middleware fires the capacity alert webhook and receives a non-200 response or timeout:

Phase 1 — Retry: Middleware executes 3 automatic retries with exponential backoff.

Phase 2 — Fallback (all 3 retries exhausted): Middleware pushes a fallback alert directly to #dev_ops via a native Slack API webhook call.

(Source: client confirmed 2026-09-18)

7. Business Rules

8. Acceptance Criteria

9. Changelog