Designing an API That Finance Teams Actually Understand
By Amara Okafor
Most payment APIs are designed by engineers for engineers. That works until the CFO asks why the reconciliation report doesn’t match the bank statement, and the engineer has to explain the difference between captured_amount and settled_amount.
The Problem
Our original API had 47 distinct status values for a payment object. Each one was technically correct and architecturally justified. But when we watched non-technical users try to understand the payment lifecycle, they got lost at status number three.
The Solution
We introduced a dual-layer status system. The technical layer retains full granularity for engineering teams. The business layer collapses everything into five states that map directly to accounting concepts: Pending, Completed, Failed, Refunded, Disputed.
Impact
- Integration time dropped from 5 days average to 1.5 days
- Support tickets related to payment status decreased 72%
- Self-serve onboarding completion rate increased from 34% to 78%