Class: Nombaone::Resources::Settlements

Inherits:
BaseResource show all
Defined in:
lib/nombaone/resources/settlements.rb,
sig/nombaone/resources.rbs

Overview

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.

Instance Method Summary collapse

Methods inherited from BaseResource

#encode, #initialize, #request, #request_page

Constructor Details

This class inherits a constructor from Nombaone::Resources::BaseResource

Instance Method Details

#create_payout(amount_in_kobo:, bank_code:, account_number:, request_options: {}) ⇒ NombaObject

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.

Examples:

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}" }
)

Parameters:

  • amount_in_kobo (Integer) —

    integer kobo (₦1.00 = 100).

  • bank_code (String) —

    CBN 3-digit bank code.

  • account_number (String)
  • request_options (Hash) (defaults to: {})

Returns:

Raises:



80
81
82
83
84
85
86
87
88
 
# File 'lib/nombaone/resources/settlements.rb', line 80

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: ,
          },
          options: request_options)
end

#list(status: OMIT, limit: OMIT, cursor: OMIT, request_options: {}) ⇒ Page<NombaObject>

List settlements, newest first.

Parameters:

  • status (String) (defaults to: OMIT) —

    filter by settlement status.

  • limit (Integer) (defaults to: OMIT) —

    page size, 1–100 (API default 20).

  • cursor (String) (defaults to: OMIT) —

    opaque cursor from a previous page.

  • request_options (Hash) (defaults to: {})

Returns:



26
27
28
29
30
 
# File 'lib/nombaone/resources/settlements.rb', line 26

def list(status: OMIT, limit: OMIT, cursor: OMIT, request_options: {})
  request_page("/settlements",
               query: { status: status, limit: limit, cursor: cursor },
               options: request_options)
end

#refund(id, amount_in_kobo: OMIT, request_options: {}) ⇒ NombaObject

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.

Parameters:

  • id (String) —

    nbo…stl

  • amount_in_kobo (Integer) (defaults to: OMIT) —

    integer kobo; defaults server-side to the full remaining refundable amount.

  • request_options (Hash) (defaults to: {})

Returns:

Raises:



54
55
56
57
 
# File 'lib/nombaone/resources/settlements.rb', line 54

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

#retrieve(id, request_options: {}) ⇒ NombaObject

Retrieve a settlement by id.

Parameters:

  • id (String) —

    nbo…stl

  • request_options (Hash) (defaults to: {})
  • request_options: (Nombaone::request_options) (defaults to: {})

Returns:

Raises:



15
16
17
 
# File 'lib/nombaone/resources/settlements.rb', line 15

def retrieve(id, request_options: {})
  request(:get, "/settlements/#{encode(id)}", options: request_options)
end

#retrieve_escrow(request_options: {}) ⇒ NombaObject

Your escrow lock and available-to-withdraw balance.

Parameters:

  • request_options (Hash) (defaults to: {})
  • request_options: (Nombaone::request_options) (defaults to: {})

Returns:



36
37
38
 
# File 'lib/nombaone/resources/settlements.rb', line 36

def retrieve_escrow(request_options: {})
  request(:get, "/settlements/escrow", options: request_options)
end