API Reference Nomba One v#0.1.0

The official Elixir SDK for the Nomba One subscription-billing API.

A non-2xx response with a status the SDK has no more-specific struct for.

What forcing one billing cycle produced. outcome is the cycle's billing result (paid | past_due | pending | open); invoice is the Nombaone.Invoice the cycle produced.

401 — a missing, invalid, revoked, or wrong-environment API key.

400 — the request could not be understood.

Billing KPIs, computed from the ledger on read — never stored, never stale. mrr_in_kobo is monthly recurring revenue in integer kobo. dunning_funnel is a Nombaone.DunningFunnel.

Your org-wide billing + dunning policy — how hard and when the engine retries, payday bias, grace windows, and collection defaults.

A hosted-checkout handoff: send the customer to checkout_link, the PCI-scoped hosted page where they enter their card.

The API client — configuration plus the HTTP engine's context.

409 — conflicts with current state (including idempotency reuse/in-progress).

The request never completed — DNS failure, connection reset, or TLS error. reason carries the underlying transport term.

A reusable discount rule. Applying a coupon to a customer or subscription creates a Nombaone.Discount — the coupon is the rule, the discount is one application of it.

Coupons — discount rules you apply via Nombaone.Customers.apply_discount/4 or Nombaone.Subscriptions.apply_discount/4.

A customer's live credit position: the total balance_in_kobo (integer kobo) plus the grants behind it.

A grant of credit that future invoices draw down before charging any rail.

A subscriber — the person or business you bill.

Customers — the people and businesses you bill.

A coupon applied to a customer or subscription (the application, not the coupon itself).

An entry in the append-only domain-event log — the audit trail behind every webhook.

One retry in a recovery run. status is one of scheduled, attempting, succeeded, rescheduled, card_update_required, exhausted.

Recovery funnel counts inside a metrics window.

Where a subscription stands in recovery. past_due is not canceled — read grace_access_until before cutting a subscriber off. attempts are Nombaone.DunningAttempt structs.

Errors are a feature.

Your escrow lock and what is actually withdrawable right now. All amounts integer kobo (₦1.00 = 100).

One entry in the event catalog: when the event fires and which data keys (payload) it carries.

Events — the append-only log behind every webhook. Webhook delivery is at-least-once; this log is your reconciliation backstop when a delivery was missed or you need to backfill.

What a billing cycle produced. You never create invoices — subscription cycles do; amounts are locked at finalization. All *_in_kobo amounts are integer kobo (₦1.00 = 100).

One line on an invoice. amount_in_kobo is integer kobo (₦1.00 = 100) and is negative for discount and credit lines. kind is one of subscription, proration, discount, credit, adjustment.

Invoices — read what the billing engine produced; void what should never be collected. You never create invoices — subscription cycles do.

What mandate creation hands back — consent is still pending at this point.

Direct-debit mandates (NIBSS). Creation is asynchronous: the mandate starts consent_pending and activates only after the customer authorizes it with their bank — the engine fires payment_method.attached / payment_method.updated. Don't poll; listen for the webhook, and don't charge before it's active (MANDATE_NOT_ACTIVE / MANDATE_CONSENT_PENDING).

Metrics — MRR, churn, and the dunning funnel, computed from the ledger on read.

404 — no resource at that id in this environment.

Organization settings — configuration, not a billing object. Billing + dunning policy lives under Nombaone.Organization.Billing.

Billing + dunning policy under /organization/billing.

One page of a list result — the items on this page plus everything needed to keep going.

Cursor-pagination metadata, returned at the top level of every list response.

How a customer pays. Card and mandate are pull rails (the engine initiates the debit); a virtual account is the push rail (the customer sends a transfer and the engine matches it). Never contains a PAN or token.

Payment methods — cards (via hosted checkout), direct-debit mandates (see Nombaone.Mandates), and virtual accounts for the transfer rail.

A withdrawal of settled funds to your bank account. status is one of pending, ledger_posted, succeeded, failed. Amounts integer kobo.

403 — a valid key, but not allowed (missing scope, foreign resource).

What you sell — "Pro", "Starter". A plan holds the name and description; its prices (amount + cadence) live underneath it (Nombaone.Plans.Prices).

Plans — your catalog. Prices (amount + cadence) nest underneath a plan via Nombaone.Plans.Prices.

Prices nested under a plan — create and list. Read and deactivate prices directly via Nombaone.Prices.

How much a plan costs per billing interval. Prices are immutable once created — to change pricing, create a new price and deactivate the old one. Existing subscriptions keep the price they were sold at.

Prices — the amounts and cadences plans are sold at. Create and list them under a plan via Nombaone.Plans.Prices; this namespace reads and deactivates them directly.

429 — slow down. retry_after is the seconds until the window rolls over (the SDK already honored it on automatic retries); limit/remaining mirror the X-RateLimit-* headers.

A refund of a settlement's tenant share (the platform fee stays). status is one of pending, ledger_only, succeeded, failed. Amounts integer kobo.

The full result of a call, returned when you pass with_response: true as a per-call option. data is exactly what you would otherwise receive; the rest is transport metadata — the request_id to quote to support, the HTTP status, and the raw response headers (rate-limit info and friends).

Returned by Nombaone.WebhookEndpoints.rotate_secret/3 — the new signing_secret, shown exactly once.

Sandbox only. Simulation instruments that make billing outcomes happen on demand — no cron waits, no real cards. These endpoints exist only on the sandbox deployment; calling them with a live key raises ArgumentError locally, before any network request.

One phase of a subscription schedule: start_index, price_id, quantity, consumed_at.

5xx — something failed on NombaOne's side. Safe to retry (the SDK already did).

The integer-kobo split of one collection into platform fee + tenant share.

Settlements — where collected money lands, and how it leaves (refunds, payouts) under the escrow lock.

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.

A priced line within a subscription: id, price_id, quantity.

A queued change that applies at a period boundary instead of mid-cycle.

Subscriptions — the core object. Create one against a customer and a price; the engine handles cycles, invoices, retries, and recovery.

Read-only view into a subscription's recovery state. past_due usually means "not yet", not "no" — check grace_access_until before cutting access.

Scheduled (next-cycle) changes queued against a subscription — the safe way to switch billing intervals (mid-cycle interval proration is unsupported).

Org-level configuration: limits, settlement mode, branding, and webhook + Nomba-account status. Nested config is fully modeled — billing is a Nombaone.TenantSettings.Billing, webhook a Nombaone.TenantSettings.Webhook, nomba_account a Nombaone.TenantSettings.NombaAccount.

Org billing configuration: limits, settlement mode, platform fee, grace, and branding. settlement_mode is split_at_collection or collect_then_payout.

Tenant branding: display_name, support_email, logo_url, primary_color_hex.

Grace defaults: grace_period_hours, dunning_max_attempts.

The linked Nomba account: account_ref, status.

Platform fee configuration. min_in_kobo/max_in_kobo are integer kobo.

Org webhook config: url, signing_secret_prefix, configured.

A single attempt exceeded its timeout budget. Retried automatically.

The pluggable HTTP back-end.

The default transport: Erlang's built-in :httpc, so the SDK ships with zero HTTP dependencies.

A preview of the next cycle's invoice — nothing is charged or stored. All *_in_kobo amounts are integer kobo (₦1.00 = 100).

422 — one or more fields are invalid. See fields for the per-field messages (a map of field path → list of messages).

A dedicated NUBAN the customer pushes bank transfers to.

One attempt-tracked delivery of an event to one endpoint. status is one of pending, succeeded, failed, dead. event_id (nbo…evt) is the dedupe key.

A URL you registered to receive signed event deliveries. enabled_events is the list of event types fanned out to this endpoint (["*"] means everything). Only the signing_secret_prefix is shown here — the full secret is returned once, at create/rotate.

Returned by Nombaone.WebhookEndpoints.create/3 only — the one time the full signing_secret is visible. Store it immediately; it is not recoverable later (only rotatable).

Webhook endpoints — register and manage the URLs that receive signed events.

Deliveries under a webhook endpoint: inspect and replay.

A verified, parsed webhook delivery.

The underlying domain event carried by a delivery: id (nbo…evt — the dedupe key), type, and created_at.

The minted event (event, type) and how many endpoint deliveries fired (delivered_count).

Webhook signature or timestamp verification failed. Reject the delivery.

Verify and parse incoming NombaOne webhook deliveries.