Best practices
Production recommendations for running Core integrations.
This page collects the operational practices that separate a Core integration that works in sandbox from one that survives production. Most of them are not optional — they are how you keep the ledger consistent, prevent duplicates when the network blinks, and respond quickly when something goes wrong.
If you are deploying Core to handle real money, treat this page as a checklist before launch and as a reference during incidents.
This page is a best-practices scaffold. The full version will include concrete examples, anti-patterns to avoid, and runbooks for the most common production failure modes.
Idempotency on every write
Every write to Core — creating a ledger transaction, issuing a card, triggering a payout — must include an idempotency key. Without it, a network timeout will silently double-write.
Reconcile against the ledger, not your cache
Core's ledger is the source of truth. Your application database may go out of sync; the ledger does not. Build a reconciliation job that periodically compares your view of balances against the ledger and surfaces drift.
Webhooks are not replacements for polling
Webhooks fire async and can arrive out of order or be retried. For final-state operations (settled transactions, completed payouts), poll the API at the moment your business logic depends on the result. Use webhooks to wake your system; use the API to confirm.
Rotate keys on a schedule
API keys do not expire automatically. Rotate them at least every 90 days and immediately after any suspected exposure. Keep a documented rotation procedure that does not require human memory.
Log the request ID
Every Core response carries a request ID. Log it on every request and include it in your error reporting. When you escalate an issue to Mono Support, the request ID is the fastest path to diagnosis.
Antipatterns to avoid
- Reusing one API key across staging and production.
- Hardcoding webhook URLs without a way to rotate them.
- Treating the synchronous response of a payout as confirmation of settlement.
- Holding ledger entries in memory between processes — always write through.