A unified API can make several providers look consistent at the payment-initiation layer. Recurring billing still needs commercial state above that API.
What a unified payment API can solve
- one authentication pattern;
- one charge/collection interface;
- provider routing;
- normalized provider responses;
- common webhook handling.
What recurring billing still needs
- plans and recurring rules;
- invoices or obligations;
- one-to-many payment attempts;
- grace and recovery policy;
- service/account state;
- reconciliation and settlement evidence.
The layer model
Merchant product → Subscription/billing rules → Invoice/obligation → Payment orchestration API → Provider/wallet → Reconciliation evidence
The payment API sits inside the lifecycle. It does not own the whole lifecycle.
Why this distinction matters
If a business stores its billing state only inside provider transactions, changing provider becomes a data migration and product rewrite.
Keeping the invoice model above the payment API makes provider replacement, multi-wallet support and regional expansion much easier.
A concrete example
Suppose a merchant sells a monthly membership in Kenya and Uganda. A unified payments API may let the product call one endpoint for M-PESA in Kenya and MTN MoMo in Uganda. That is valuable integration work, but the API still does not know whether the November membership invoice already exists, whether the customer is in grace, whether a previous attempt is unresolved or whether service should be restored after payment.
Those decisions belong to billing. The payment API should receive a specific amount to collect, return provider evidence and expose enough state for the billing system to decide what happens next.
Three anti-patterns to avoid
- Using provider transaction IDs as invoice IDs. This breaks when one invoice has several attempts.
- Creating a new invoice every time the unified API is called. A retry is not a new commercial obligation.
- Letting raw provider status trigger service changes directly. Normalize the payment result, resolve the invoice, then apply merchant policy.
What a clean boundary looks like
The billing layer owns customer/account, plan, amount due, due date, grace and recovery. The payment layer owns provider routing, payment initiation, provider identifiers, raw responses and payment verification. Reconciliation connects both sides afterwards.
This boundary also improves portability: a merchant can replace a PSP or add a wallet without migrating subscription history or rewriting every service rule.
The design test
Ask whether the merchant could replace the underlying payment provider without recreating subscriptions, invoices and customer history. If the answer is no, provider integration and billing state are still too tightly coupled.
