Class: Nombaone::Resources::Mandates

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

Overview

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).

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(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: {}) ⇒ NombaObject

Create a mandate. Requires an Idempotency-Key (sent automatically).

Examples:

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
)

Parameters:

  • customer_ref (String) —

    the customer this mandate belongs to (nbo…cus).

  • customer_account_number (String)
  • bank_code (String) —

    CBN 3-digit bank code (058 GTB · 044 Access · 033 UBA · …).

  • customer_name (String)
  • customer_account_name (String)
  • customer_phone_number (String)
  • customer_address (String)
  • narration (String) —

    shown on the customer's statement.

  • max_amount_in_kobo (Integer) —

    hard per-debit ceiling, integer kobo (₦1.00 = 100). Charges above it fail with MANDATE_MAX_AMOUNT_EXCEEDED.

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

    defaults to "monthly" server-side.

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

    local date-time (no zone); defaults to tomorrow.

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

    local date-time (no zone); defaults to one year out.

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

Returns:

  • (NombaObject) —

    the pending mandate setup; relay its consent_instruction to the customer, then wait for the webhook.



38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/nombaone/resources/mandates.rb', line 38

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: ,
            bank_code: bank_code,
            customer_name: customer_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

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

Check a mandate's current standing. Returns the underlying payment-method row (its status moves consent_pending → active).

Parameters:

  • id (String) —

    nbo…pmt

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

Returns:



66
67
68
 
# File 'lib/nombaone/resources/mandates.rb', line 66

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