What should a payment API surface actually cover?
A modern payments API is rarely just "charge a card." A platform building a real integration typically needs API coverage across several distinct areas, and evaluating a provider on payment processing alone misses most of what determines how much engineering effort the integration actually costs:
- Onboarding — programmatically starting and tracking merchant applications, not just a hosted form with no visibility into status.
- Payment acceptance — card-present and card-not-present transactions, hosted payment pages, and increasingly, alternative payment methods.
- Tokenization — storing and reusing payment credentials as tokens rather than raw card numbers, both for recurring billing and for keeping the platform's own systems out of PCI scope where possible.
- Webhooks — real-time event delivery for things like transaction status changes, chargebacks, and onboarding decisions, rather than requiring the platform to poll for status.
- Reporting — transaction-level and portfolio-level data access, ideally through the same API surface as everything else rather than a separate reporting-only system.
A provider that only covers the first two of these will work for a simple integration, but forces the platform's engineering team to build its own solutions for tokenization, event handling, and reporting — which is exactly the kind of infrastructure work embedding payments is supposed to avoid.
Why does tokenized data access matter specifically for developers?
Beyond the compliance argument for tokenization (covered in more detail in our tokenization explainer), there's a practical developer reason to care: a platform whose API access is scoped to tokens and payment references, rather than raw card data, never has to build or maintain PCI-scoped infrastructure for that data in the first place. That has real engineering consequences — fewer systems requiring PCI DSS assessment, less specialized security tooling, and a smaller blast radius if any single system is compromised.
A platform evaluating a payments API should specifically check whether its own systems ever receive raw card data at any point, or whether every interaction happens through tokens and references. The latter is a meaningfully lower-maintenance position to build from.
What should webhook design actually look like?
Real-time event delivery matters because payments status changes asynchronously — an underwriting decision, a transaction settling, a chargeback being filed, none of these happen in the same request/response cycle as the action that triggered them. A well-designed webhook system should cover at minimum:
- Onboarding status changes — application received, under review, approved, declined.
- Transaction lifecycle events — authorized, captured, settled, refunded.
- Dispute and chargeback events — filed, evidence due, resolved.
- Account-level events — a merchant's processing status changing for any operational reason.
A platform that has to poll an API repeatedly to detect these changes is building unnecessary infrastructure to compensate for a gap in the provider's API design.
What does a good developer onboarding experience look like?
Independent of the API's technical capability, a few things determine whether developers can actually get productive quickly:
- Self-service sandbox access — the ability to start building and testing without a sales conversation gating the first API call.
- Complete, accurate documentation — covering not just endpoints, but the actual event flows and edge cases a real integration will encounter.
- A clear path from sandbox to production — including whatever security, data-handling, or API-conduct review is required before reaching live merchants, communicated up front rather than discovered midway through a build.
- SDKs for common platforms, reducing the amount of boilerplate integration code needed for popular languages and frameworks.
What should this look like end to end?
Put together, a payments API surface that developers can actually build on efficiently covers onboarding, orchestration, tokenized data access, and reporting through one consistent interface — with webhooks handling the asynchronous parts rather than requiring polling — and a sandbox-first path to get started without a sales cycle blocking the first integration attempt.
This is the shape of NGnair's developer platform: REST APIs and SDKs across onboarding, orchestration, commerce, and reporting, tokenized data access by default, and a self-service sandbox before any conversation is required.
The short version
A modern payments API surface should cover onboarding, orchestration, tokenized credential handling, webhooks, and reporting — not just transaction processing. Evaluating a provider on "can it charge a card" alone misses most of what actually determines how much engineering work an integration ends up costing.
Traditional ISO integrations were often too narrow for this to even be a fair comparison — NGnair's developer platform was built specifically so a real integration is possible, not a workaround.
