FiveM Discord refund bot runbook for API outages with fallback payouts

Refund automation reduces staff workload, but it also creates a single point of failure: external APIs. When Discord has an incident, your payment provider throttles requests, or your bot host loses connectivity, refund requests pile up fast and players lose trust. This runbook gives you a repeatable response for FiveM communities that process refunds through Discord (tickets, slash commands, role-gated approvals) and need a safe fallback payout path. The goal is continuity: keep players informed, prevent double-payouts, and preserve an audit trail you can defend later.

Define your outage triggers and severity levels

Start by writing down what “outage” means for your refund bot. Many teams wait until refunds fail loudly, but you can detect issues earlier by monitoring command latency, webhook delivery, and ticket backlog. Define severity levels so staff respond consistently and you can decide when to switch to fallback payouts.

• SEV-1 (Full stop): Refund commands fail for most users (e.g., Discord API errors 5xx, bot cannot read/write channels, payment API down).
• SEV-2 (Degraded): Refund commands work intermittently, approvals lag, or rate limits trigger (HTTP 429) but some requests succeed.
• SEV-3 (Partial impact): Only one component fails (e.g., log webhooks failing, but payouts still process).

Concrete signals to watch: a spike in failed interactions for /refund, Discord gateway disconnects, missing messages in #refund-logs, or tickets stuck in “Awaiting payout” for more than your SLA (for example, 30 minutes). If you use a system like LD Refund System, review its bot logs and any configured webhooks to see whether failures are Discord-side, host-side, or provider-side before you change workflows.

Prepare Discord roles, permissions, and channels for incident mode

Fallback payouts only work if your Discord structure is ready. Set up an “incident mode” that limits who can approve refunds, where evidence is posted, and how updates reach players. This reduces chaos and prevents well-meaning staff from issuing duplicate payouts.

• Roles: Create @Refund Manager (final approval), @Refund Staff (triage), and @Audit (read-only access to logs).
• Permissions: Lock #refund-logs to staff only; allow @Refund Manager to Manage Messages (for redaction) and View Audit Log; restrict ticket close permissions to @Refund Staff and above.
• Channels: #refund-status (read-only announcements), #refund-ops (staff coordination), #refund-logs (immutable-style logs; no casual chat), and a private category for refund tickets.
• Bot permissions: Ensure the refund bot has Read Message History, Send Messages, Manage Threads (if you use threads), and Add Reactions (if approvals use reactions).

Incident response workflow: detect, communicate, and freeze risky actions

When an outage hits, your first job is to stop the situation from getting worse. That means confirming impact, communicating clearly, and freezing any action that could cause duplicate payouts. Use a simple, repeatable sequence so any on-call staff member can run it.

1. Confirm the scope: Check Discord Status, your bot host status, and payment provider dashboards. Validate by running a staff-only command (e.g., /refund healthcheck) or reviewing recent error logs (429/5xx).
2. Declare incident: Post in #refund-status with a timestamp, what’s impacted (refund approvals/payouts/logs), and the next update time. Pin the message.
3. Freeze automation: Disable auto-approval rules, scheduled payout jobs, and any “retry on fail” loops that could replay transactions. If your bot supports maintenance mode, enable it; otherwise revoke its payout credential temporarily.
4. Switch intake to tickets only: Require all refund requests to be filed via a ticket form (e.g., /ticket refund) so evidence and timestamps stay consistent.
5. Start an incident log: In #refund-ops, create a thread named “INC-YYYYMMDD-Refunds” and log decisions, staff involved, and any manual payouts issued.

Example announcement text that works: “Refund processing is currently delayed due to an upstream API issue. Please submit requests via the Refund Ticket form. Do not open duplicate tickets. Next update in 30 minutes.” Keep it factual and avoid guessing timelines you can’t guarantee.

Fallback payouts: manual processing without losing auditability

Fallback payouts should be predictable and auditable. Your goal is to keep the community moving while ensuring you can reconcile later when APIs recover. Decide in advance which refunds qualify for fallback payouts and what proof is required. Common FiveM cases include: vehicle deletion after a server crash, duplicate store charge, or lost inventory due to a script error.

• Eligibility rule: Only refunds with complete evidence (purchase ID, Steam/Discord ID mapping, timestamp, and reason) qualify for fallback.
• Caps: Apply a per-user cap during incidents (e.g., one refund per 24 hours) to limit abuse.
• Two-person integrity: @Refund Staff collects evidence; @Refund Manager approves and executes payout.
• Evidence checklist: Screenshot of store receipt, in-game proof (clip or server log), and ticket transcript link.
• Unique reference: Assign a manual reference like REF-INC-20260220-014 and include it in the ticket and the payout note.

For payout methods, pick the least risky option your community already supports. If you refund in-game currency, use an admin command that writes to server logs (e.g., a framework command that logs to console and to a database table). If you refund via a store panel, use its “manual adjustment” feature and paste the unique reference. Avoid direct DMs with “I sent it” confirmations; keep everything inside the ticket channel for traceability.

If your refund tooling supports exporting or syncing transactions (some communities use LD Refund System for structured refund records), export the incident window later and match each manual reference to a ticket URL. The key is that every fallback payout must have: who approved it, what was paid, why it was paid, and where the evidence lives.

Logging and reconciliation: make the post-incident cleanup painless

Outages end, but the risk continues during recovery. Reconciliation is where teams accidentally issue duplicates—especially if the bot retries old jobs or staff reprocess tickets that already received fallback payouts. Treat recovery as a controlled change.

1. Stabilize first: Confirm Discord interactions and webhooks work, then confirm payment API success with a single test transaction in a staff-only sandbox ticket.
2. Keep maintenance mode on: Re-enable bot connectivity but keep payouts disabled until reconciliation is complete.
3. Build a reconciliation table: For the incident window, list Ticket URL, Discord ID, FiveM identifier (license/steam), amount/type, manual reference, approver, and payout method.
4. Deduplicate: Search for repeated purchase IDs, repeated Discord IDs, and tickets reopened after closure. Flag anything ambiguous for manager review.
5. Restore automation: Re-enable scheduled jobs and auto-approvals only after you confirm no backlog item will be retried into a second payout.
6. Close the loop: Post a final #refund-status update summarizing what happened, what changed, and where players can report issues.

Logging specifics that help: send bot events to #refund-logs via webhook (include interaction ID, user ID, and result), mirror critical actions to a database table, and enable Discord Audit Log access for @Audit. If you use ticket bots (e.g., Ticket Tool), export transcripts for any fallback payout and attach them to your reconciliation record.

Hardening for next time: monitoring, rate limits, and playbook drills

After you resolve the incident, convert the pain into prevention. Most refund outages are predictable: Discord rate limits, expired tokens, webhook failures, or provider-side maintenance. A small amount of monitoring and a short drill once per quarter will reduce downtime and staff confusion.

• Monitoring: Track command error rate, average interaction latency, and webhook delivery failures. Alert @Refund Staff when failures exceed a threshold for 5 minutes.
• Rate limits: Implement exponential backoff for 429 responses; avoid spamming edits to the same message; batch log messages where possible.
• Credential hygiene: Store API keys in environment variables; rotate tokens after incidents; restrict who can access bot hosting panels.
• Redundancy: Host the bot with a process manager (PM2/systemd) and health checks; keep a read-only status page message template ready.
• Drills: Run a 15-minute tabletop exercise: simulate “Discord API degraded” and practice switching to ticket-only intake and manual references.

Finally, keep your runbook in the same place staff already work: a pinned message in #refund-ops and a short doc in your staff knowledge base. Include screenshots of role settings, the exact fallback payout checklist, and the reconciliation table template. When the next outage happens, you won’t be inventing policy under pressure—you’ll be executing it.