Developer documentation
Accounts and credit events
Report complete, idempotent and correctable account histories.
Account model
An account belongs to the reporting institution and one subject. external_account_id is your stable ledger identifier and must be unique within the institution. Account creation also records ACCOUNT_OPENED.
| Field | Rule |
|---|---|
| currency | Three uppercase letters; DCR by default |
| principal / balance | Non-negative, at most two decimal places |
| interest_rate_bps | Basis points from 0 to 100,000 |
| opened_at / maturity_at | Maturity cannot precede opening |
| status | CURRENT, PAID, PAST_DUE, DELINQUENT, DEFAULTED, RESTRUCTURED, WRITTEN_OFF, CANCELLED or DISPUTED |
| metadata | Small, non-sensitive integration context only |
Event vocabulary
Use the most specific event type. Supported types are ACCOUNT_OPENED, ACCOUNT_UPDATED, PAYMENT_DUE, PAYMENT_MADE, PARTIAL_PAYMENT, PAYMENT_LATE, ACCOUNT_CURRENT, DELINQUENCY_STARTED, DELINQUENCY_CURED, DEFAULT_REPORTED, DEFAULT_CURED, ACCOUNT_RESTRUCTURED, ACCOUNT_WRITTEN_OFF, ACCOUNT_PAID, ACCOUNT_CLOSED, BALANCE_UPDATED, LIMIT_CHANGED, DISPUTE_OPENED, DISPUTE_RESOLVED and CORRECTION.
- occurred_at is when the real-world event occurred; reported_at is assigned by RCN.
- balance_after updates the account balance when supplied.
- DEFAULT_REPORTED defaults to MODERATE severity if default_severity is omitted.
- State transitions are validated. An impossible transition returns 409 and must not be retried unchanged.
- source_reference should be unique and traceable to your ledger event.
Corrections, never destructive rewrites
Submit CORRECTION with supersedes_event_id and correction_reason. The original event must belong to the same account. RCN preserves both records so the audit trail explains what changed and why.
{
"event_type": "CORRECTION",
"occurred_at": "2026-08-18T04:40:00Z",
"supersedes_event_id": "EVENT_ID",
"correction_reason": "Payment amount transposed during ledger export",
"amount": 125.00,
"balance_after": 900.00,
"source_reference": "correction-ledger-8841-v2"
}Bulk reporting
- POST /accounts/bulk accepts at most 100 accounts.
- POST /events/bulk accepts at most 500 events; each item includes credit_account_id.
- Both require Idempotency-Key. Split larger imports deterministically and preserve batch-level reconciliation records.
- A failed batch should be inspected as a unit; do not blindly replay with a different key until you know whether anything committed.