Expand description
The official Rust SDK for the NombaOne 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.
The client derives its host from your API-key prefix — nbo_sandbox_… talks
to the sandbox, nbo_live_… to production — so a quickstart is three objects
away from an active subscription. See the crate README and the examples/
directory for runnable end-to-end walkthroughs.
§Money is integer kobo
Every amount is an integer in kobo, the minor unit of the naira
(₦1.00 = 100). 250_000 is ₦2,500 — not ₦250,000. There are no floats and
no decimal strings; currency is always "NGN". Multiply naira by 100
exactly once, at the edge of your system.
§Feature flags
reqwest-transport(default) — the built-in async transport (reqwest+rustls). Disable it to supply your ownHttpTransport.blocking— a synchronous client mirroring the async surface, for CLIs and non-asynccallers.
Re-exports§
pub use webhook_events::EventRef;pub use webhook_events::WebhookEvent;pub use webhook_events::WebhookEventData;pub use webhook_events::WebhookEventType;pub use transport::testing;test-util
Modules§
- transport
- The HTTP transport layer: the pluggable
HttpTransporttrait, and the one internal function that runs the retry loop, computes the idempotency key exactly once, enforces the per-attempt timeout, parses the envelope, and returns the unwrapped result or a typedError. - webhook_
events - The typed outbound event catalog — one variant per event type the platform
emits, mirrored from the API’s frozen catalog and kept open: an event
type this SDK version does not know still parses (as
WebhookEventType::OtherwithWebhookEventData::Other). - webhooks
- Verify and parse incoming NombaOne webhook deliveries. No API key required — verification needs only the endpoint’s signing secret, so these are free functions you can call from a webhook receiver that holds nothing else.
Structs§
- Advance
Cycle Result - What forcing one billing cycle produced.
- ApiCall
- A prepared API call.
awaitit for the resource, or chain per-call options —idempotency_key,header,timeout,max_retries— and finish withwith_responsefor the request id and raw headers: - ApiError
- A non-2xx response from the API. Carries everything the error envelope said:
the stable
codeto branch on, thehinttelling you how to fix it, thedoc_urlinto the error reference, per-field validation errors on 422s, and therequest_idto quote to support. - Billing
Metrics - Billing KPIs for a window.
- Billing
Metrics Params - Filters for
Metrics::billing. - Billing
Settings - Your billing and dunning policy.
- Billing
Settings Update Params - Inputs to
OrganizationBilling::update. - Branding
- Your organization’s branding.
- Checkout
Setup - A hosted-checkout setup — send the customer to
checkout_linkto add a card. - Coupon
- A reusable discount rule. Exactly one of
amount_off_in_koboorpercent_offis set. - Coupon
Create Params - Inputs to
Coupons::create. Set exactly one ofamount_off_in_koboorpercent_off(COUPON_INVALID_DEFINITIONotherwise). - Coupon
List Params - Filters for
Coupons::list. - Coupon
Update Params - Inputs to
Coupons::update. - Coupons
- Coupons — reusable discount rules. Access via
Nombaone::coupons. - Credit
Balance - A customer’s live credit position: the total balance plus the grants behind it.
- Credit
Grant - A grant of credit that future invoices draw down — oldest grant first — before charging any payment rail.
- Customer
- A subscriber — the person or business you bill.
- Customer
Apply Discount Params - Inputs to
Customers::apply_discount. - Customer
Create Params - Inputs to
Customers::create. - Customer
Grant Credit Params - Inputs to
Customers::grant_credit. - Customer
List Params - Filters for
Customers::list. - Customer
Update Params - Inputs to
Customers::update. At least one field must be set. - Customers
- Customers — the people and businesses you bill. Access via
Nombaone::customers. - Discount
- A coupon applied to a customer or subscription — the application of a coupon, not the coupon itself.
- Domain
Event - An entry in the append-only domain-event log — the audit trail behind every
webhook.
payloadcarries the samedatayour endpoints receive. - Dunning
Attempt - One retry in a recovery run.
- Dunning
Funnel - The dunning funnel — how recovery attempts are distributed across states.
- Dunning
State - Where a subscription stands in recovery.
past_dueis not canceled — readgrace_access_untilbefore cutting a subscriber off. - Error
Code - A stable, machine-readable error identifier. Branch on it — it never changes for a given failure — rather than on the human-readable message.
- Escrow
- Your escrow position — held funds and what is withdrawable.
- Event
Catalog Entry - One entry in the event catalog: when the event fires and the fields its payload carries.
- Event
List Params - Filters for
Events::list. - Events
- Events — the append-only domain-event log. Access via
Nombaone::events. - Grace
Settings - Grace and dunning summary shown on organization settings.
- Headers
- A case-insensitive, ordered collection of HTTP headers. Used to expose the
raw response headers on
crate::Responseand inside the transport. - Invoice
- What a billing cycle produced.
- Invoice
Line Item - One line on an invoice. Amounts are integer kobo; discount and credit lines are negative.
- Invoice
List Params - Filters for
Invoices::list. - Invoice
Void Params - Inputs to
Invoices::void. - Invoices
- Invoices — read and void. Access via
Nombaone::invoices. - List
Page Params - Filters for
Subscriptions::list_eventsand dunning attempt lists. - Mandate
Create Params - Inputs to
Mandates::create. - Mandate
Setup - The result of starting a mandate — the reference plus the instruction to show the customer for consent.
- Mandates
- Mandates — NIBSS direct debit. Access via
Nombaone::mandates. - Metrics
- Metrics — billing KPIs from the ledger. Access via
Nombaone::metrics. - Nomba
Account - The linked Nomba account block of
TenantSettings. - Nombaone
- The NombaOne API client. Cheap to clone (it is reference-counted); share one across your application.
- Nombaone
Builder - A builder for
Nombaone. Obtain one withNombaone::builder. - Organization
- Organization settings. Access via
Nombaone::organization. - Organization
Billing - Your billing and dunning policy. Access via
Organization::billing. - Page
- One page of a list, plus everything needed to fetch the next.
- Pagination
- The cursor-pagination block returned at the top level of every list response.
- Paginator
- A prepared list request.
awaitit for the firstPage, or turn it into astreamof items (orpages). - Payment
Method - A stored way to charge a customer.
- Payment
Method List Params - Filters for
PaymentMethods::list. - Payment
Method Setup Params - Inputs to
PaymentMethods::setup. - Payment
Method Virtual Account Params - Inputs to
PaymentMethods::create_virtual_account. - Payment
Methods - Payment methods — cards, mandates, and virtual accounts. Access via
Nombaone::payment_methods. - Payout
- A payout to your bank account.
- Payout
Create Params - Inputs to
Settlements::create_payout. - Plan
- A product in your catalog. A plan has many
Prices. - Plan
Create Params - Inputs to
Plans::create. - Plan
List Params - Filters for
Plans::list. - Plan
Price List Params - Filters for
PlanPrices::list. - Plan
Prices - The prices nested under a plan. Access via
Plans::prices. - Plan
Update Params - Inputs to
Plans::update. At least one field must be set. - Plans
- Plans — your catalog. Access via
Nombaone::plans. - Platform
Fee - The platform fee configuration.
- Price
- An immutable amount and cadence. Prices never change once created — make a new one and archive the old plan instead.
- Price
Create Params - Inputs to create a price (via
PlanPrices::create). - Price
List Params - Filters for
Prices::list. - Prices
- Prices — immutable amounts and cadences. Access via
Nombaone::prices. Create prices under a plan withplans().prices().create(…). - Refund
- A refund against a settlement.
- Response
- The full result of a call, for when you need more than the resource itself.
Obtain one with
ApiCall::with_response. - Rotated
Webhook Secret - A rotated signing secret — the result of
WebhookEndpoints::rotate_secret. The new secret is shown once. - Sandbox
- Sandbox only. Access via
Nombaone::sandbox. Every method fails locally (before any network call) if the client was built with a live key. - Sandbox
Payment Method Params - Inputs to
Sandbox::create_payment_method. - Sandbox
Simulate Webhook Params - Inputs to
Sandbox::simulate_webhook. - Schedule
Phase - One phase of a subscription schedule.
- Settlement
- A settlement — money owed to you from a collected payment.
- Settlement
List Params - Filters for
Settlements::list. - Settlement
Refund Params - Inputs to
Settlements::refund. - Settlements
- Settlements, refunds, payouts, and escrow. Access via
Nombaone::settlements. - Subscription
- One customer’s recurring relationship with one price. The engine bills it every cycle, retries failures through dunning, and reports every transition as a webhook event.
- Subscription
Apply Discount Params - Inputs to
Subscriptions::apply_discount. - Subscription
Cancel Params - Inputs to
Subscriptions::cancel. - Subscription
Change Params - Inputs to
Subscriptions::change. At least one ofprice_id,quantity, orinterval_switchis required. - Subscription
Create Params - Inputs to
Subscriptions::create. - Subscription
Dunning - A read-only view into a subscription’s recovery state
(
subscriptions().dunning()). - Subscription
Item - One item on a subscription (a price and a quantity).
- Subscription
List Params - Filters for
Subscriptions::list. - Subscription
Pause Params - Inputs to
Subscriptions::pause. - Subscription
Resubscribe Params - Inputs to
Subscriptions::resubscribe. - Subscription
Schedule - A queued change that applies at a period boundary instead of mid-cycle.
- Subscription
Schedule Create Params - Inputs to
SubscriptionSchedules::create. - Subscription
Schedules - Scheduled (next-cycle) changes queued against a subscription
(
subscriptions().schedule()). - Subscription
Update Params - Inputs to
Subscriptions::update(metadata / default payment method only). For price/quantity/interval changes useSubscriptions::change. - Subscription
Update Payment Method Params - Inputs to
Subscriptions::update_payment_method. Exactly one ofpayment_method_referenceorcheckout_token. - Subscriptions
- Subscriptions — the core object. Access via
Nombaone::subscriptions. - Tenant
Billing - The billing block of
TenantSettings. - Tenant
Settings - Your organization’s settings.
- Tenant
Settings Update Params - Inputs to
Organization::update. - Tenant
Webhook - The webhook block of
TenantSettings. - Upcoming
Invoice - A preview of the next cycle’s invoice — nothing is charged or stored.
- Virtual
Account - A bank-transfer virtual account (NUBAN) issued for a customer.
- Webhook
Delivery - A single delivery attempt-target for an event.
- Webhook
Delivery List Params - Filters for
WebhookEndpointDeliveries::list. - Webhook
Endpoint - A registered webhook endpoint.
- Webhook
Endpoint Create Params - Inputs to
WebhookEndpoints::create. - Webhook
Endpoint Deliveries - The deliveries for an endpoint. Access via
WebhookEndpoints::deliveries. - Webhook
Endpoint Update Params - Inputs to
WebhookEndpoints::update. - Webhook
Endpoint With Secret - A newly-created webhook endpoint, including its signing secret. The secret is shown exactly once — store it now.
- Webhook
Endpoints - Webhook endpoint management. Access via
Nombaone::webhook_endpoints. - Webhook
Simulation - The minted event and how many endpoint deliveries fired.
- Webhook
Verification Error - Webhook signature or timestamp verification failed — reject the delivery. Each failure mode carries a distinct message.
Enums§
- ApiError
Kind - The HTTP class of an
ApiError. Rust has no inheritance, so where other SDKs subclass by status this SDK exposes akind— match on it the same way. - Billing
Reason - Why a billing cycle produced an invoice.
- Billing
Scheme - How a
Pricecomputes its amount. - Cancel
Mode - Whether a cancellation takes effect now or at the period boundary.
- Cancellation
Reason - Why a subscription was canceled.
- Collection
Method - How an invoice is collected.
- Coupon
Duration - How long a
Coupon’s discount lasts once applied. - Credit
Source - Where a
CreditGrantcame from. OnlyManualandGoodwillare valid at grant time; the others appear on system-created grants. - Discount
Status - The lifecycle state of a
Discount. - Dunning
Attempt Status - The status of a single
DunningAttempt. - Dunning
Branch - The recovery branch a dunning attempt took.
- Dunning
Status - Where a subscription stands in recovery — the dunning statuses plus
None(not in dunning). - Effective
At - When a scheduled change applies.
- Error
- Everything this SDK can return as an error — API failures, transport problems, webhook verification failures, and client misconfiguration.
- Field
- A three-state value for the handful of request fields the API lets you
clear by sending an explicit JSON
null— for example a customer’sphone. The three states are: - Invoice
List Status - The invoice statuses accepted by the
Invoices::listfilter. Mirrors a wire quirk:partially_paidis a valid invoice status but not a valid filter. - Invoice
Status - The lifecycle state of an
Invoice.PartiallyPaidcan appear on an invoice object, but is not accepted as a list filter — seeInvoiceListStatus. - Line
Item Kind - The kind of an
InvoiceLineItem. - Mandate
Frequency - How often a mandate may be debited.
- Mode
- The environment a key — and everything created with it — lives in. It is
encoded in the API-key prefix (
nbo_sandbox_…ornbo_live_…). Sandbox and live are fully isolated: a resource created in one does not exist in the other. - Payment
Method Kind - The kind of a
PaymentMethod. - Payment
Method Status - The lifecycle state of a
PaymentMethod. - Payout
Status - The lifecycle state of a
Payout. - Plan
Status - The lifecycle state of a
Plan. - Price
Interval - The billing cadence of a
Price. - Proration
Behavior - How a mid-cycle change handles proration.
- Proration
Credit Policy - How downgrade proration credit is handled.
- Refund
Status - The lifecycle state of a
Refund. - Sandbox
Payment Method Behavior - The deterministic outcome a sandbox payment method produces when charged. These are the “magic values” of the sandbox — behaviors, not card numbers.
- Schedule
Status - The state of a
SubscriptionSchedule. - Settlement
Mode - How settlements are handled for your organization.
- Settlement
Status - The lifecycle state of a
Settlement. - Subscription
Status - The lifecycle state of a
Subscription. Involuntary churn isCanceledwithcancellation_reason = Involuntary— there is no separatechurnedstatus (there is asubscription.churnedevent). - Usage
Type - How usage is metered for a
Price. - Webhook
Delivery Status - The delivery state of a
WebhookDelivery.
Constants§
- KNOWN_
ERROR_ CODES - Every public error code known to this SDK version, vendored from the
platform’s
PUBLIC_ERROR_CODES. The live set is open: the API may emit a code this list does not yet name. - LIVE_
BASE_ URL - The default host for the live environment. Selected automatically for a
nbo_live_…key. - SANDBOX_
BASE_ URL - The default host for the sandbox environment. Selected automatically for a
nbo_sandbox_…key. - VERSION
- The version of this crate. Sent as part of the
User-Agenton every request.
Type Aliases§
- Item
Stream - A boxed stream of items —
Unpin, so you can calltry_next/nexton it (withfutures_util’sStreamExt/TryStreamExt) without pinning first. - Kobo
- An amount of money in kobo, the integer minor unit of the naira
(
₦1.00 = 100). Every money field in the API is an integer number of kobo — never a float, never a decimal string.250_000is ₦2,500, not ₦250,000. Multiply naira by 100 exactly once, at the edge of your system. - Metadata
- Free-form annotations you can attach to most resources. Values are arbitrary JSON — not string-only. The SDK never transforms these keys or values.
- Page
Stream - A boxed stream of whole
Pages.