Skip to main content

Crate nombaone

Crate nombaone 

Source
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 own HttpTransport.
  • blocking — a synchronous client mirroring the async surface, for CLIs and non-async callers.

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 HttpTransport trait, 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 typed Error.
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::Other with WebhookEventData::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§

AdvanceCycleResult
What forcing one billing cycle produced.
ApiCall
A prepared API call. await it for the resource, or chain per-call options — idempotency_key, header, timeout, max_retries — and finish with with_response for the request id and raw headers:
ApiError
A non-2xx response from the API. Carries everything the error envelope said: the stable code to branch on, the hint telling you how to fix it, the doc_url into the error reference, per-field validation errors on 422s, and the request_id to quote to support.
BillingMetrics
Billing KPIs for a window.
BillingMetricsParams
Filters for Metrics::billing.
BillingSettings
Your billing and dunning policy.
BillingSettingsUpdateParams
Inputs to OrganizationBilling::update.
Branding
Your organization’s branding.
CheckoutSetup
A hosted-checkout setup — send the customer to checkout_link to add a card.
Coupon
A reusable discount rule. Exactly one of amount_off_in_kobo or percent_off is set.
CouponCreateParams
Inputs to Coupons::create. Set exactly one of amount_off_in_kobo or percent_off (COUPON_INVALID_DEFINITION otherwise).
CouponListParams
Filters for Coupons::list.
CouponUpdateParams
Inputs to Coupons::update.
Coupons
Coupons — reusable discount rules. Access via Nombaone::coupons.
CreditBalance
A customer’s live credit position: the total balance plus the grants behind it.
CreditGrant
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.
CustomerApplyDiscountParams
Inputs to Customers::apply_discount.
CustomerCreateParams
Inputs to Customers::create.
CustomerGrantCreditParams
Inputs to Customers::grant_credit.
CustomerListParams
Filters for Customers::list.
CustomerUpdateParams
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.
DomainEvent
An entry in the append-only domain-event log — the audit trail behind every webhook. payload carries the same data your endpoints receive.
DunningAttempt
One retry in a recovery run.
DunningFunnel
The dunning funnel — how recovery attempts are distributed across states.
DunningState
Where a subscription stands in recovery. past_due is not canceled — read grace_access_until before cutting a subscriber off.
ErrorCode
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.
EventCatalogEntry
One entry in the event catalog: when the event fires and the fields its payload carries.
EventListParams
Filters for Events::list.
Events
Events — the append-only domain-event log. Access via Nombaone::events.
GraceSettings
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::Response and inside the transport.
Invoice
What a billing cycle produced.
InvoiceLineItem
One line on an invoice. Amounts are integer kobo; discount and credit lines are negative.
InvoiceListParams
Filters for Invoices::list.
InvoiceVoidParams
Inputs to Invoices::void.
Invoices
Invoices — read and void. Access via Nombaone::invoices.
ListPageParams
Filters for Subscriptions::list_events and dunning attempt lists.
MandateCreateParams
Inputs to Mandates::create.
MandateSetup
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.
NombaAccount
The linked Nomba account block of TenantSettings.
Nombaone
The NombaOne API client. Cheap to clone (it is reference-counted); share one across your application.
NombaoneBuilder
A builder for Nombaone. Obtain one with Nombaone::builder.
Organization
Organization settings. Access via Nombaone::organization.
OrganizationBilling
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. await it for the first Page, or turn it into a stream of items (or pages).
PaymentMethod
A stored way to charge a customer.
PaymentMethodListParams
Filters for PaymentMethods::list.
PaymentMethodSetupParams
Inputs to PaymentMethods::setup.
PaymentMethodVirtualAccountParams
Inputs to PaymentMethods::create_virtual_account.
PaymentMethods
Payment methods — cards, mandates, and virtual accounts. Access via Nombaone::payment_methods.
Payout
A payout to your bank account.
PayoutCreateParams
Inputs to Settlements::create_payout.
Plan
A product in your catalog. A plan has many Prices.
PlanCreateParams
Inputs to Plans::create.
PlanListParams
Filters for Plans::list.
PlanPriceListParams
Filters for PlanPrices::list.
PlanPrices
The prices nested under a plan. Access via Plans::prices.
PlanUpdateParams
Inputs to Plans::update. At least one field must be set.
Plans
Plans — your catalog. Access via Nombaone::plans.
PlatformFee
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.
PriceCreateParams
Inputs to create a price (via PlanPrices::create).
PriceListParams
Filters for Prices::list.
Prices
Prices — immutable amounts and cadences. Access via Nombaone::prices. Create prices under a plan with plans().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.
RotatedWebhookSecret
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.
SandboxPaymentMethodParams
Inputs to Sandbox::create_payment_method.
SandboxSimulateWebhookParams
Inputs to Sandbox::simulate_webhook.
SchedulePhase
One phase of a subscription schedule.
Settlement
A settlement — money owed to you from a collected payment.
SettlementListParams
Filters for Settlements::list.
SettlementRefundParams
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.
SubscriptionApplyDiscountParams
Inputs to Subscriptions::apply_discount.
SubscriptionCancelParams
Inputs to Subscriptions::cancel.
SubscriptionChangeParams
Inputs to Subscriptions::change. At least one of price_id, quantity, or interval_switch is required.
SubscriptionCreateParams
Inputs to Subscriptions::create.
SubscriptionDunning
A read-only view into a subscription’s recovery state (subscriptions().dunning()).
SubscriptionItem
One item on a subscription (a price and a quantity).
SubscriptionListParams
Filters for Subscriptions::list.
SubscriptionPauseParams
Inputs to Subscriptions::pause.
SubscriptionResubscribeParams
Inputs to Subscriptions::resubscribe.
SubscriptionSchedule
A queued change that applies at a period boundary instead of mid-cycle.
SubscriptionScheduleCreateParams
Inputs to SubscriptionSchedules::create.
SubscriptionSchedules
Scheduled (next-cycle) changes queued against a subscription (subscriptions().schedule()).
SubscriptionUpdateParams
Inputs to Subscriptions::update (metadata / default payment method only). For price/quantity/interval changes use Subscriptions::change.
SubscriptionUpdatePaymentMethodParams
Inputs to Subscriptions::update_payment_method. Exactly one of payment_method_reference or checkout_token.
Subscriptions
Subscriptions — the core object. Access via Nombaone::subscriptions.
TenantBilling
The billing block of TenantSettings.
TenantSettings
Your organization’s settings.
TenantSettingsUpdateParams
Inputs to Organization::update.
TenantWebhook
The webhook block of TenantSettings.
UpcomingInvoice
A preview of the next cycle’s invoice — nothing is charged or stored.
VirtualAccount
A bank-transfer virtual account (NUBAN) issued for a customer.
WebhookDelivery
A single delivery attempt-target for an event.
WebhookDeliveryListParams
Filters for WebhookEndpointDeliveries::list.
WebhookEndpoint
A registered webhook endpoint.
WebhookEndpointCreateParams
Inputs to WebhookEndpoints::create.
WebhookEndpointDeliveries
The deliveries for an endpoint. Access via WebhookEndpoints::deliveries.
WebhookEndpointUpdateParams
Inputs to WebhookEndpoints::update.
WebhookEndpointWithSecret
A newly-created webhook endpoint, including its signing secret. The secret is shown exactly once — store it now.
WebhookEndpoints
Webhook endpoint management. Access via Nombaone::webhook_endpoints.
WebhookSimulation
The minted event and how many endpoint deliveries fired.
WebhookVerificationError
Webhook signature or timestamp verification failed — reject the delivery. Each failure mode carries a distinct message.

Enums§

ApiErrorKind
The HTTP class of an ApiError. Rust has no inheritance, so where other SDKs subclass by status this SDK exposes a kind — match on it the same way.
BillingReason
Why a billing cycle produced an invoice.
BillingScheme
How a Price computes its amount.
CancelMode
Whether a cancellation takes effect now or at the period boundary.
CancellationReason
Why a subscription was canceled.
CollectionMethod
How an invoice is collected.
CouponDuration
How long a Coupon’s discount lasts once applied.
CreditSource
Where a CreditGrant came from. Only Manual and Goodwill are valid at grant time; the others appear on system-created grants.
DiscountStatus
The lifecycle state of a Discount.
DunningAttemptStatus
The status of a single DunningAttempt.
DunningBranch
The recovery branch a dunning attempt took.
DunningStatus
Where a subscription stands in recovery — the dunning statuses plus None (not in dunning).
EffectiveAt
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’s phone. The three states are:
InvoiceListStatus
The invoice statuses accepted by the Invoices::list filter. Mirrors a wire quirk: partially_paid is a valid invoice status but not a valid filter.
InvoiceStatus
The lifecycle state of an Invoice. PartiallyPaid can appear on an invoice object, but is not accepted as a list filter — see InvoiceListStatus.
LineItemKind
The kind of an InvoiceLineItem.
MandateFrequency
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_… or nbo_live_…). Sandbox and live are fully isolated: a resource created in one does not exist in the other.
PaymentMethodKind
The kind of a PaymentMethod.
PaymentMethodStatus
The lifecycle state of a PaymentMethod.
PayoutStatus
The lifecycle state of a Payout.
PlanStatus
The lifecycle state of a Plan.
PriceInterval
The billing cadence of a Price.
ProrationBehavior
How a mid-cycle change handles proration.
ProrationCreditPolicy
How downgrade proration credit is handled.
RefundStatus
The lifecycle state of a Refund.
SandboxPaymentMethodBehavior
The deterministic outcome a sandbox payment method produces when charged. These are the “magic values” of the sandbox — behaviors, not card numbers.
ScheduleStatus
The state of a SubscriptionSchedule.
SettlementMode
How settlements are handled for your organization.
SettlementStatus
The lifecycle state of a Settlement.
SubscriptionStatus
The lifecycle state of a Subscription. Involuntary churn is Canceled with cancellation_reason = Involuntary — there is no separate churned status (there is a subscription.churned event).
UsageType
How usage is metered for a Price.
WebhookDeliveryStatus
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-Agent on every request.

Type Aliases§

ItemStream
A boxed stream of items — Unpin, so you can call try_next / next on it (with futures_util’s StreamExt/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_000 is ₦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.
PageStream
A boxed stream of whole Pages.