nombaone 0.1.0

data/lib/nombaone/resources/mandates.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Nombaone
+  module Resources
+    # 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 sweeps for activation and fires
+    # `payment_method.attached` / `payment_method.updated`. Don't poll in a tight
+    # loop; listen for the webhook, and don't charge before it's active
+    # (`MANDATE_NOT_ACTIVE` / `MANDATE_CONSENT_PENDING`).
+    class Mandates < BaseResource
+      # Create a mandate. Requires an `Idempotency-Key` (sent automatically).
+      #
+      # @param customer_ref [String] the customer this mandate belongs to (`nbo…cus`).
+      # @param customer_account_number [String]
+      # @param bank_code [String] CBN 3-digit bank code (058 GTB · 044 Access · 033 UBA · …).
+      # @param customer_name [String]
+      # @param customer_account_name [String]
+      # @param customer_phone_number [String]
+      # @param customer_address [String]
+      # @param narration [String] shown on the customer's statement.
+      # @param max_amount_in_kobo [Integer] hard per-debit ceiling, **integer
+      #   kobo** (₦1.00 = 100). Charges above it fail with `MANDATE_MAX_AMOUNT_EXCEEDED`.
+      # @param frequency [String] defaults to `"monthly"` server-side.
+      # @param start_date [String] local date-time (no zone); defaults to tomorrow.
+      # @param end_date [String] local date-time (no zone); defaults to one year out.
+      # @param request_options [Hash]
+      # @return [NombaObject] the pending mandate setup; relay its
+      #   `consent_instruction` to the customer, then wait for the webhook.
+      #
+      # @example
+      #   mandate = nombaone.mandates.create(
+      #     customer_ref: customer.id, customer_account_number: "0123456789", bank_code: "058",
+      #     customer_name: "Ada Lovelace", customer_account_name: "Ada Lovelace",
+      #     customer_phone_number: "+2348012345678", customer_address: "1 Marina, Lagos",
+      #     narration: "Acme Pro subscription", max_amount_in_kobo: 500_000
+      #   )
+      def create(customer_ref:, customer_account_number:, bank_code:, customer_name:,
+                 customer_account_name:, customer_phone_number:, customer_address:, narration:,
+                 max_amount_in_kobo:, frequency: OMIT, start_date: OMIT, end_date: OMIT,
+                 request_options: {})
+        request(:post, "/mandates",
+                body: {
+                  customer_ref: customer_ref,
+                  customer_account_number: customer_account_number,
+                  bank_code: bank_code,
+                  customer_name: customer_name,
+                  customer_account_name: customer_account_name,
+                  customer_phone_number: customer_phone_number,
+                  customer_address: customer_address,
+                  narration: narration,
+                  max_amount_in_kobo: max_amount_in_kobo,
+                  frequency: frequency,
+                  start_date: start_date,
+                  end_date: end_date,
+                },
+                options: request_options)
+      end
+
+      # Check a mandate's current standing. Returns the underlying
+      # **payment-method** row (its `status` moves `consent_pending` → `active`).
+      #
+      # @param id [String] `nbo…pmt`
+      # @param request_options [Hash]
+      # @return [NombaObject] a payment method.
+      def retrieve(id, request_options: {})
+        request(:get, "/mandates/#{encode(id)}", options: request_options)
+      end
+    end
+  end
+end

data/lib/nombaone/resources/metrics.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Nombaone
+  module Resources
+    # Metrics — MRR, churn, and the dunning funnel, computed from the ledger on
+    # read (never stored, never stale).
+    class Metrics < BaseResource
+      # Billing KPIs over a window (defaults to a recent window server-side).
+      #
+      # @param from [String] ISO-8601 date-time, start of the window.
+      # @param to [String] ISO-8601 date-time, end of the window.
+      # @param request_options [Hash]
+      # @return [NombaObject] with `mrr_in_kobo`, `active_count`, churn counts,
+      #   and the `dunning_funnel`.
+      #
+      # @example
+      #   metrics = nombaone.metrics.billing
+      #   puts "MRR ₦#{metrics.mrr_in_kobo / 100}"
+      def billing(from: OMIT, to: OMIT, request_options: {})
+        request(:get, "/metrics/billing", query: { from: from, to: to }, options: request_options)
+      end
+    end
+  end
+end

data/lib/nombaone/resources/organization.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Nombaone
+  module Resources
+    # Billing + dunning policy under `nombaone.organization.billing`.
+    class OrganizationBilling < BaseResource
+      # Read the org's billing + dunning policy.
+      #
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def retrieve(request_options: {})
+        request(:get, "/organization/billing", options: request_options)
+      end
+
+      # Update the billing policy. PUT semantics, but only supplied keys change.
+      #
+      # @param partial_collection_enabled [Boolean]
+      # @param proration_credit_policy [String] `"credit_next_cycle"` or `"none"`.
+      # @param dunning_max_attempts [Integer] 1–10.
+      # @param dunning_intervals_hours [Array<Integer>]
+      # @param dunning_max_window_hours [Integer] must be ≥ the largest interval.
+      # @param grace_period_hours [Integer]
+      # @param payday_days [Array<Integer>] days of month, 1–31.
+      # @param payday_pull_forward_days [Integer] 0–28.
+      # @param payday_bias_enabled [Boolean]
+      # @param default_collection_method [String] `"charge_automatically"` or `"send_invoice"`.
+      # @param comms_enabled [Boolean]
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      #
+      # @example
+      #   nombaone.organization.billing.update(payday_bias_enabled: true, payday_days: [25, 28, 30])
+      def update(partial_collection_enabled: OMIT, proration_credit_policy: OMIT,
+                 dunning_max_attempts: OMIT, dunning_intervals_hours: OMIT,
+                 dunning_max_window_hours: OMIT, grace_period_hours: OMIT, payday_days: OMIT,
+                 payday_pull_forward_days: OMIT, payday_bias_enabled: OMIT,
+                 default_collection_method: OMIT, comms_enabled: OMIT, request_options: {})
+        request(:put, "/organization/billing",
+                body: {
+                  partial_collection_enabled: partial_collection_enabled,
+                  proration_credit_policy: proration_credit_policy,
+                  dunning_max_attempts: dunning_max_attempts,
+                  dunning_intervals_hours: dunning_intervals_hours,
+                  dunning_max_window_hours: dunning_max_window_hours,
+                  grace_period_hours: grace_period_hours,
+                  payday_days: payday_days,
+                  payday_pull_forward_days: payday_pull_forward_days,
+                  payday_bias_enabled: payday_bias_enabled,
+                  default_collection_method: default_collection_method,
+                  comms_enabled: comms_enabled,
+                },
+                options: request_options)
+      end
+    end
+
+    # Organization settings — configuration, not a billing object.
+    class Organization < BaseResource
+      # Billing + dunning policy.
+      # @return [OrganizationBilling]
+      def billing
+        @billing ||= OrganizationBilling.new(@client)
+      end
+
+      # Read org-level settings (limits, settlement mode, branding, statuses).
+      #
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def retrieve(request_options: {})
+        request(:get, "/organization", options: request_options)
+      end
+
+      # Update tenant-editable settings. At least one field is required.
+      #
+      # @param monthly_request_quota [Integer]
+      # @param settlement_mode [String] `"split_at_collection"` or `"collect_then_payout"`.
+      # @param branding [Hash] `display_name`, `support_email`, `logo_url`, `primary_color_hex`.
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def update(monthly_request_quota: OMIT, settlement_mode: OMIT, branding: OMIT,
+                 request_options: {})
+        request(:put, "/organization",
+                body: {
+                  monthly_request_quota: monthly_request_quota,
+                  settlement_mode: settlement_mode,
+                  branding: branding,
+                },
+                options: request_options)
+      end
+    end
+  end
+end

data/lib/nombaone/resources/payment_methods.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Nombaone
+  module Resources
+    # Payment methods — cards (via hosted checkout), direct-debit mandates (see
+    # `nombaone.mandates`), and virtual accounts for the transfer rail.
+    #
+    # 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 treat a collect as instantly final).
+    class PaymentMethods < BaseResource
+      # Start a hosted-checkout card capture. Card entry happens on the PCI
+      # hosted page — no card data ever touches your servers. The method appears
+      # as `setup_pending` until the customer completes checkout.
+      #
+      # @param customer_ref [String] the customer this card will belong to (`nbo…cus`).
+      # @param amount_in_kobo [Integer] the validation charge, **integer kobo** (₦1.00 = 100).
+      # @param callback_url [String] where the hosted checkout returns the customer.
+      # @param request_options [Hash]
+      # @return [NombaObject] with a `checkout_link` to redirect the customer to.
+      #
+      # @example
+      #   setup = nombaone.payment_methods.setup(
+      #     customer_ref: customer.id, amount_in_kobo: 5_000, callback_url: "https://example.com/return"
+      #   )
+      #   # redirect the customer to setup.checkout_link
+      def setup(customer_ref:, amount_in_kobo:, callback_url:, request_options: {})
+        request(:post, "/payment-methods/setup",
+                body: {
+                  customer_ref: customer_ref,
+                  amount_in_kobo: amount_in_kobo,
+                  callback_url: callback_url,
+                },
+                options: request_options)
+      end
+
+      # Issue a dedicated virtual account (NUBAN) so the customer can pay by
+      # bank transfer. The engine matches inbound transfers to invoices by
+      # reference and exact integer-kobo amount.
+      #
+      # @param customer_ref [String] the customer to issue the account for (`nbo…cus`).
+      # @param expected_amount [Integer] optional expected amount hint, integer kobo.
+      # @param expiry_date [String] optional ISO date the account should expire.
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def create_virtual_account(customer_ref:, expected_amount: OMIT, expiry_date: OMIT,
+                                 request_options: {})
+        request(:post, "/payment-methods/virtual-account",
+                body: {
+                  customer_ref: customer_ref,
+                  expected_amount: expected_amount,
+                  expiry_date: expiry_date,
+                },
+                options: request_options)
+      end
+
+      # Retrieve a payment method by id.
+      #
+      # @param id [String] `nbo…pmt`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::NotFoundError] 404 `PAYMENT_METHOD_NOT_FOUND`
+      def retrieve(id, request_options: {})
+        request(:get, "/payment-methods/#{encode(id)}", options: request_options)
+      end
+
+      # List payment methods, newest first.
+      #
+      # @param customer_ref [String] filter to one customer (`nbo…cus`). Note
+      #   the wire filter name is `customerRef`.
+      # @param limit [Integer] page size, 1–100 (API default 20).
+      # @param cursor [String] opaque cursor from a previous page.
+      # @param request_options [Hash]
+      # @return [Page<NombaObject>]
+      def list(customer_ref: OMIT, limit: OMIT, cursor: OMIT, request_options: {})
+        request_page("/payment-methods",
+                     query: { customer_ref: customer_ref, limit: limit, cursor: cursor },
+                     options: request_options)
+      end
+
+      # Make this the customer's default payment method.
+      #
+      # @param id [String] `nbo…pmt`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def set_default(id, request_options: {})
+        request(:post, "/payment-methods/#{encode(id)}/default", body: {}, options: request_options)
+      end
+
+      # Detach a payment method. Subscriptions still billing against it will
+      # need a replacement (`SUBSCRIPTION_PAYMENT_METHOD_REQUIRED` at next charge
+      # otherwise).
+      #
+      # @param id [String] `nbo…pmt`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def remove(id, request_options: {})
+        request(:delete, "/payment-methods/#{encode(id)}", options: request_options)
+      end
+    end
+  end
+end

data/lib/nombaone/resources/plans.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Nombaone
+  module Resources
+    # Prices nested under a plan (create/list); reach `nombaone.prices` for
+    # reads and deactivation.
+    class PlanPrices < BaseResource
+      # Create a price under a plan. Prices are immutable once created.
+      #
+      # @param plan_id [String] `nbo…pln`
+      # @param unit_amount_in_kobo [Integer] amount per unit per interval,
+      #   **integer kobo** (₦1.00 = 100). `250_000` is ₦2,500 — not ₦250,000.
+      # @param interval [String] `"day"` `"week"` `"month"` `"year"`.
+      # @param interval_count [Integer] bill every N intervals (default 1).
+      # @param usage_type [String] `"licensed"` (default) or `"metered"`.
+      # @param billing_scheme [String] `"per_unit"` (default) or `"tiered"`.
+      # @param trial_period_days [Integer] free-trial days at subscribe time.
+      # @param metadata [Hash]
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      #
+      # @example
+      #   price = nombaone.plans.prices.create(plan.id, unit_amount_in_kobo: 250_000, interval: "month")
+      def create(plan_id, unit_amount_in_kobo:, interval:, interval_count: OMIT, usage_type: OMIT,
+                 billing_scheme: OMIT, trial_period_days: OMIT, metadata: OMIT, request_options: {})
+        request(:post, "/plans/#{encode(plan_id)}/prices",
+                body: {
+                  unit_amount_in_kobo: unit_amount_in_kobo,
+                  interval: interval,
+                  interval_count: interval_count,
+                  usage_type: usage_type,
+                  billing_scheme: billing_scheme,
+                  trial_period_days: trial_period_days,
+                  metadata: metadata,
+                },
+                options: request_options)
+      end
+
+      # List a plan's prices, newest first.
+      #
+      # @param plan_id [String] `nbo…pln`
+      # @param limit [Integer] page size, 1–100 (API default 20).
+      # @param cursor [String] opaque cursor from a previous page.
+      # @param request_options [Hash]
+      # @return [Page<NombaObject>]
+      def list(plan_id, limit: OMIT, cursor: OMIT, request_options: {})
+        request_page("/plans/#{encode(plan_id)}/prices",
+                     query: { limit: limit, cursor: cursor }, options: request_options)
+      end
+    end
+
+    # Plans — your catalog. A plan holds the name and description; its prices
+    # (amount + cadence) live underneath it (`nombaone.plans.prices`).
+    #
+    # @example
+    #   plan = nombaone.plans.create(name: "Pro")
+    #   price = nombaone.plans.prices.create(plan.id, unit_amount_in_kobo: 250_000, interval: "month")
+    class Plans < BaseResource
+      # Prices nested under a plan.
+      # @return [PlanPrices]
+      def prices
+        @prices ||= PlanPrices.new(@client)
+      end
+
+      # Create a plan.
+      #
+      # @param name [String] unique within your organization (`PLAN_NAME_TAKEN` on reuse).
+      # @param description [String]
+      # @param metadata [Hash]
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::ConflictError] 409 `PLAN_NAME_TAKEN`
+      def create(name:, description: OMIT, metadata: OMIT, request_options: {})
+        request(:post, "/plans",
+                body: { name: name, description: description, metadata: metadata },
+                options: request_options)
+      end
+
+      # Retrieve a plan by id.
+      #
+      # @param id [String] `nbo…pln`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::NotFoundError] 404 `PLAN_NOT_FOUND`
+      def retrieve(id, request_options: {})
+        request(:get, "/plans/#{encode(id)}", options: request_options)
+      end
+
+      # Update a plan's mutable fields. At least one field is required.
+      #
+      # @param id [String] `nbo…pln`
+      # @param name [String]
+      # @param description [String, nil] pass `nil` to clear the description.
+      # @param metadata [Hash]
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def update(id, name: OMIT, description: OMIT, metadata: OMIT, request_options: {})
+        request(:patch, "/plans/#{encode(id)}",
+                body: { name: name, description: description, metadata: metadata },
+                options: request_options)
+      end
+
+      # List plans, newest first.
+      #
+      # @param status [String] `"active"` or `"archived"`.
+      # @param limit [Integer] page size, 1–100 (API default 20).
+      # @param cursor [String] opaque cursor from a previous page.
+      # @param request_options [Hash]
+      # @return [Page<NombaObject>]
+      def list(status: OMIT, limit: OMIT, cursor: OMIT, request_options: {})
+        request_page("/plans",
+                     query: { status: status, limit: limit, cursor: cursor },
+                     options: request_options)
+      end
+
+      # Archive a plan — it stops being subscribable but its history stays.
+      #
+      # @param id [String] `nbo…pln`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::ConflictError] 409 `PLAN_ALREADY_ARCHIVED`
+      # @raise [Nombaone::ConflictError] 409 `PLAN_HAS_ACTIVE_SUBSCRIBERS` —
+      #   migrate or cancel those subscriptions first.
+      def archive(id, request_options: {})
+        request(:post, "/plans/#{encode(id)}/archive", body: {}, options: request_options)
+      end
+    end
+  end
+end

data/lib/nombaone/resources/prices.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Nombaone
+  module Resources
+    # 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.
+    #
+    # 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.
+    class Prices < BaseResource
+      # Retrieve a price by id.
+      #
+      # @param id [String] `nbo…prc`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::NotFoundError] 404 `PRICE_NOT_FOUND`
+      def retrieve(id, request_options: {})
+        request(:get, "/prices/#{encode(id)}", options: request_options)
+      end
+
+      # List prices across all plans, newest first.
+      #
+      # @param plan_ref [String] filter to one plan's prices (`nbo…pln`). Note
+      #   the wire filter name is `planRef`.
+      # @param active [Boolean] filter by the active flag.
+      # @param limit [Integer] page size, 1–100 (API default 20).
+      # @param cursor [String] opaque cursor from a previous page.
+      # @param request_options [Hash]
+      # @return [Page<NombaObject>]
+      #
+      # @example
+      #   page = nombaone.prices.list(plan_ref: plan.id, active: true)
+      def list(plan_ref: OMIT, active: OMIT, limit: OMIT, cursor: OMIT, request_options: {})
+        request_page("/prices",
+                     query: { plan_ref: plan_ref, active: active, limit: limit, cursor: cursor },
+                     options: request_options)
+      end
+
+      # Deactivate a price so no new subscriptions can be created against it.
+      # Existing subscriptions are unaffected — prices are immutable history.
+      #
+      # @param id [String] `nbo…prc`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::ConflictError] 409 `PRICE_ALREADY_INACTIVE`
+      def deactivate(id, request_options: {})
+        request(:post, "/prices/#{encode(id)}/deactivate", body: {}, options: request_options)
+      end
+    end
+  end
+end

data/lib/nombaone/resources/sandbox.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Nombaone
+  module Resources
+    # **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 any of them with a live key raises
+    # locally, **before any network request**.
+    class Sandbox < BaseResource
+      # **Sandbox only.** Mint a ready, chargeable test payment method whose
+      # `behavior` decides every future charge outcome deterministically.
+      #
+      # @param customer_id [String] `nbo…cus`
+      # @param behavior [String] `"success"` (default), `"decline_insufficient_funds"`,
+      #   `"decline_expired_card"`, `"decline_do_not_honor"`, or `"requires_otp"`.
+      # @param kind [String] `"card"` (default) or `"mandate"`.
+      # @param request_options [Hash]
+      # @return [NombaObject] a payment method.
+      #
+      # @example
+      #   method = nombaone.sandbox.create_payment_method(
+      #     customer_id: customer.id, behavior: "decline_insufficient_funds"
+      #   )
+      def create_payment_method(customer_id:, behavior: OMIT, kind: OMIT, request_options: {})
+        assert_sandbox!
+        request(:post, "/sandbox/payment-methods",
+                body: { customer_id: customer_id, behavior: behavior, kind: kind },
+                options: request_options)
+      end
+
+      # **Sandbox only.** The test clock: run the subscription's next billing
+      # cycle right now, through the real engine — invoice, charge, ledger,
+      # webhooks and all.
+      #
+      # @param subscription_id [String] `nbo…sub`
+      # @param request_options [Hash]
+      # @return [NombaObject] the cycle `outcome` and the `invoice` it produced.
+      #
+      # @example
+      #   result = nombaone.sandbox.advance_cycle(subscription.id)
+      #   result.outcome # => "paid"
+      def advance_cycle(subscription_id, request_options: {})
+        assert_sandbox!
+        request(:post, "/sandbox/subscriptions/#{encode(subscription_id)}/advance-cycle",
+                body: {}, options: request_options)
+      end
+
+      # **Sandbox only.** Emit a real, signed catalog event to your registered
+      # endpoints — the genuine pipeline (real secret, real signature, real
+      # retries), not a mock. This is how you rehearse your handler.
+      #
+      # @param type [String] any catalog event type, e.g. `"invoice.payment_failed"`.
+      # @param payload [Hash] shapes the delivery's `data` object.
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      #
+      # @example
+      #   nombaone.sandbox.simulate_webhook(
+      #     type: "invoice.payment_failed",
+      #     payload: { reference: invoice.id, reason: "insufficient_funds" }
+      #   )
+      def simulate_webhook(type:, payload: OMIT, request_options: {})
+        assert_sandbox!
+        request(:post, "/sandbox/webhooks/simulate",
+                body: { type: type, payload: payload }, options: request_options)
+      end
+
+      private
+
+      # Fail locally, before any network call, when constructed with a live key.
+      def assert_sandbox!
+        return unless @client.mode == "live"
+
+        raise Error,
+              "nombaone.sandbox.* only works with a sandbox key (nbo_sandbox_…) — the " \
+              "/v1/sandbox endpoints do not exist on the live API. Use your sandbox key to " \
+              "rehearse, then go live without the sandbox calls."
+      end
+    end
+  end
+end

data/lib/nombaone/resources/settlements.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Nombaone
+  module Resources
+    # Settlements — where collected money lands, and how it leaves (refunds,
+    # payouts) under the escrow lock. Collections split into a non-refundable
+    # platform fee plus the net to your tenant sub-account.
+    class Settlements < BaseResource
+      # Retrieve a settlement by id.
+      #
+      # @param id [String] `nbo…stl`
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::NotFoundError] 404 `SETTLEMENT_NOT_FOUND`
+      def retrieve(id, request_options: {})
+        request(:get, "/settlements/#{encode(id)}", options: request_options)
+      end
+
+      # List settlements, newest first.
+      #
+      # @param status [String] filter by settlement status.
+      # @param limit [Integer] page size, 1–100 (API default 20).
+      # @param cursor [String] opaque cursor from a previous page.
+      # @param request_options [Hash]
+      # @return [Page<NombaObject>]
+      def list(status: OMIT, limit: OMIT, cursor: OMIT, request_options: {})
+        request_page("/settlements",
+                     query: { status: status, limit: limit, cursor: cursor },
+                     options: request_options)
+      end
+
+      # Your escrow lock and available-to-withdraw balance.
+      #
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      def retrieve_escrow(request_options: {})
+        request(:get, "/settlements/escrow", options: request_options)
+      end
+
+      # Refund a settlement's tenant share. The platform fee is never refunded.
+      #
+      # **Money moves here.** The API requires an `Idempotency-Key`; the SDK
+      # sends one automatically, but pass your own stable
+      # `request_options[:idempotency_key]` so a retry from a *new process*
+      # cannot refund twice.
+      #
+      # @param id [String] `nbo…stl`
+      # @param amount_in_kobo [Integer] **integer kobo**; defaults server-side to
+      #   the full remaining refundable amount.
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::ConflictError] 409 `REFUND_ALREADY_REFUNDED`
+      # @raise [Nombaone::ValidationError] 422 `REFUND_AMOUNT_EXCEEDS_NET`
+      def refund(id, amount_in_kobo: OMIT, request_options: {})
+        request(:post, "/settlements/#{encode(id)}/refund",
+                body: { amount_in_kobo: amount_in_kobo }, options: request_options)
+      end
+
+      # Withdraw settled funds to your bank account.
+      #
+      # **Money moves here, and the `Idempotency-Key` doubles as the payout's
+      # durable `merchantTxRef`.** Always pass an explicit, stable
+      # `request_options[:idempotency_key]` (e.g. your own payout id) — an
+      # auto-generated key protects SDK-level retries, but a brand-new process
+      # retrying with a fresh key would create a **second** payout.
+      #
+      # @param amount_in_kobo [Integer] **integer kobo** (₦1.00 = 100).
+      # @param bank_code [String] CBN 3-digit bank code.
+      # @param account_number [String]
+      # @param request_options [Hash]
+      # @return [NombaObject]
+      # @raise [Nombaone::ConflictError] 409 `ESCROW_LOCKED`
+      # @raise [Nombaone::ValidationError] 422 `PAYOUT_EXCEEDS_AVAILABLE`
+      #
+      # @example
+      #   payout = nombaone.settlements.create_payout(
+      #     amount_in_kobo: 5_000_000, bank_code: "058", account_number: "0123456789",
+      #     request_options: { idempotency_key: "payout-#{my_payout_row.id}" }
+      #   )
+      def create_payout(amount_in_kobo:, bank_code:, account_number:, request_options: {})
+        request(:post, "/settlements/payout",
+                body: {
+                  amount_in_kobo: amount_in_kobo,
+                  bank_code: bank_code,
+                  account_number: account_number,
+                },
+                options: request_options)
+      end
+    end
+  end
+end