nombaone
The official Rust SDK for the Nomba One subscription-billing API — recurring billing for Nigeria over card, direct debit, bank transfer, and more, with dunning that recovers and a ledger that never loses a kobo.
[]
= "0.1"
= { = "1", = ["macros", "rt-multi-thread"] }
Async-first (built on tokio and reqwest + rustls), with an optional
blocking feature for synchronous callers. Requires Rust 1.85+. Zero unsafe.
Quickstart
Grab a sandbox key (nbo_sandbox_…) from the dashboard,
set it as NOMBAONE_API_KEY, and you are three objects away from a live
subscription:
use *;
async
The client derives its host from your key prefix — nbo_sandbox_… talks to
https://sandbox.api.nombaone.xyz, nbo_live_… to https://api.nombaone.xyz.
Server-side only; there is no publishable key to leak.
Sandbox first
The sandbox runs the real billing engine. nombaone.sandbox() gives you the
levers to make a month happen in a second:
# use *;
# async
These methods fail locally, before any network call, if used with a live key.
Money is integer kobo
Every amount in the API is an integer in kobo: ₦1.00 = 100. 250_000 is
₦2,500 — not ₦250,000. No floats, no decimal strings; currency is always
"NGN". Multiply naira by 100 exactly once, at the edge of your system. Every
money field is named ..._in_kobo and typed [Kobo] (an i64), so a mix-up is
hard to write.
Pagination
Every list returns a [Paginator]. Await it for one [Page], stream every
item with cursors handled for you, or (with the blocking feature) iterate
synchronously:
# use *;
# async
// With the `blocking` feature — no async runtime needed:
for invoice in nombaone.invoices.list.iter
Errors are a feature
Every failure is a typed [Error]. API failures are Error::Api([ApiError]),
carrying the stable code to branch on, a hint telling you exactly what to do
next, a doc_url into the error reference, per-field validation details, and the
request_id to quote to support. Classify by HTTP class with
[ApiError::kind]:
# use *;
# async
Kind ([ApiErrorKind]) |
Status | Notes |
|---|---|---|
BadRequest |
400 | malformed request |
Authentication |
401 | missing/invalid/wrong-environment key |
PermissionDenied |
403 | missing scope, foreign resource |
NotFound |
404 | wrong id or wrong environment |
Conflict |
409 | state conflicts, idempotency reuse |
Validation |
422 | error.fields has the per-field messages |
RateLimit |
429 | retry_after, rate_limit, rate_remaining |
Server |
5xx | safe to retry (the SDK already did) |
Plus Error::Connection, Error::Timeout (transport), Error::Decode,
Error::Config, and Error::WebhookVerification.
Idempotency & retries
The SDK auto-generates an Idempotency-Key for every POST and reuses it across
its automatic retries (network failures, timeouts, 408/429/5xx — 2 retries by
default, honoring Retry-After), so a blip can never double-charge. Per-call
options chain before .await:
# use *;
# use Duration;
# async
Payout note. On
settlements().create_payout(...)theIdempotency-Keydoubles as the durablemerchant_tx_ref. The auto-generated key protects retries within one process; pass your own stable key so a retry from a new process can't create a second payout.
Webhooks
Verify before you parse, and dedupe on the event id — delivery is at-least-once,
never exactly-once. The [webhooks] helpers are free functions that need no
API key — only the endpoint's signing secret:
use ;
use WebhookEventData;
// In your handler, `raw_body` is the EXACT request bytes (never re-serialized)
// and `signature` is the `X-Nombaone-Signature` header.
Capturing the raw body differs by framework — the one rule is do not let the framework parse and re-serialize it first:
- axum: extract
axum::body::Bytes(notJson); read the header fromHeaderMap. - actix-web: take
web::BytesandHttpRequest. - warp:
warp::body::bytes(). - hyper:
hyper::body::to_bytes(req.into_body()).
webhooks::generate_test_header lets you unit-test your handler without a real
delivery. Manage endpoints with nombaone.webhook_endpoints() — create and
rotate return the signing secret exactly once.
The full surface
customers (+ credit, discount) · plans (+ nested prices) · prices ·
subscriptions (pause/resume/cancel/resubscribe/change, schedule, dunning,
upcoming invoice, events) · invoices · coupons · payment_methods
(hosted-checkout cards, virtual accounts) · mandates (NIBSS direct debit) ·
settlements (escrow, refunds, payouts) · webhook_endpoints (+ deliveries,
replay) · events (+ catalog) · organization (+ billing policy) · metrics ·
sandbox — every operation in the API reference,
1:1.
Worth knowing:
- Mandates are asynchronous. They start
consent_pendingand activate when the customer's bank confirms — listen forpayment_method.updated, don't poll, don't charge early. - Bank transfer is a push rail.
payment_methods().create_virtual_account()issues a NUBAN; collection completes when the transfer arrives and reconciles. past_dueis not canceled. Readsubscriptions().dunning().retrieve()and honorgrace_access_untilbefore cutting anyone off.
Configuration
# use *;
# use Duration;
#
Bring your own HTTP stack (a proxy, a tuned client, or a test double) by
implementing [transport::HttpTransport] and passing it to .transport(...).
Feature flags
reqwest-transport(default) — the built-in async transport.blocking— synchronous terminals (.send_blocking(),.iter()) mirroring the async surface.test-util— a scriptable, recordingMockTransportfor your own tests.
Examples & development
Runnable examples live in examples/ — quickstart, pagination, the
subscription lifecycle, a webhook receiver, and a sandbox dunning rehearsal:
NOMBAONE_API_KEY=nbo_sandbox_…
Develop the SDK with cargo test; the live suite runs against a real API with
NOMBAONE_INTEGRATION=1 NOMBAONE_API_KEY=… cargo test --test integration.
Requirements & versioning
Rust 1.85+. Semantic versioning; the API itself is versioned at /v1 and
additive changes never break you. MIT licensed.