Class: Nombaone::Resources::PaymentMethods

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

Overview

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

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_virtual_account(customer_ref:, expected_amount: OMIT, expiry_date: OMIT, request_options: {}) ⇒ NombaObject

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.

Parameters:

  • customer_ref (String) —

    the customer to issue the account for (nbo…cus).

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

    optional expected amount hint, integer kobo.

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

    optional ISO date the account should expire.

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

Returns:



46
47
48
49
50
51
52
53
54
55
 
# File 'lib/nombaone/resources/payment_methods.rb', line 46

def (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

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

List payment methods, newest first.

Parameters:

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

    filter to one customer (nbo…cus). Note the wire filter name is customerRef.

  • 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:



75
76
77
78
79
 
# File 'lib/nombaone/resources/payment_methods.rb', line 75

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

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

Detach a payment method. Subscriptions still billing against it will need a replacement (SUBSCRIPTION_PAYMENT_METHOD_REQUIRED at next charge otherwise).

Parameters:

  • id (String) —

    nbo…pmt

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

Returns:



97
98
99
 
# File 'lib/nombaone/resources/payment_methods.rb', line 97

def remove(id, request_options: {})
  request(:delete, "/payment-methods/#{encode(id)}", options: request_options)
end

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

Retrieve a payment method by id.

Parameters:

  • id (String) —

    nbo…pmt

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

Returns:

Raises:



63
64
65
 
# File 'lib/nombaone/resources/payment_methods.rb', line 63

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

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

Make this the customer's default payment method.

Parameters:

  • id (String) —

    nbo…pmt

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

Returns:



86
87
88
 
# File 'lib/nombaone/resources/payment_methods.rb', line 86

def set_default(id, request_options: {})
  request(:post, "/payment-methods/#{encode(id)}/default", body: {}, options: request_options)
end

#setup(customer_ref:, amount_in_kobo:, callback_url:, request_options: {}) ⇒ NombaObject

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.

Examples:

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

Parameters:

  • customer_ref (String) —

    the customer this card will belong to (nbo…cus).

  • amount_in_kobo (Integer) —

    the validation charge, integer kobo (₦1.00 = 100).

  • callback_url (String) —

    where the hosted checkout returns the customer.

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

Returns:

  • (NombaObject) —

    with a checkout_link to redirect the customer to.



27
28
29
30
31
32
33
34
35
 
# File 'lib/nombaone/resources/payment_methods.rb', line 27

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