Class: Inttegro::Resources::PaymentMethods

Inherits:
Object
  • Object
show all
Defined in:
lib/inttegro/resources/payment_methods.rb

Overview

Payment Methods resource for tokenizing and managing customer payment instruments.

Payment methods are saved payment instruments (mobile money wallets, cards, bank accounts) that customers can reuse across purchases. Use this resource to tokenize new payment methods, verify ownership, and manage the payment method lifecycle.

See Also:

Instance Method Summary collapse

Constructor Details

#initialize(http) ⇒ PaymentMethods

Returns a new instance of PaymentMethods.

Parameters:



15
16
17
 
# File 'lib/inttegro/resources/payment_methods.rb', line 15

def initialize(http)
  @http = T.let(http, Inttegro::HTTPClient)
end

Instance Method Details

#activate(payment_method_id:) ⇒ Inttegro::PaymentMethod

Mark an inactive payment method active.

Parameters:

  • payment_method_id (String) —

    unique payment method identifier

Returns:



172
173
174
175
176
177
178
 
# File 'lib/inttegro/resources/payment_methods.rb', line 172

def activate(payment_method_id:)
  @http.post_resource(
    "/payment_methods/activate",
    Inttegro::PaymentMethod, :payment_method,
    { payment_method_id: payment_method_id }
  )
end

#archive(payment_method_id:) ⇒ Inttegro::PaymentMethod

Archive a payment method.

Parameters:

  • payment_method_id (String) —

    unique payment method identifier

Returns:



198
199
200
201
202
203
204
 
# File 'lib/inttegro/resources/payment_methods.rb', line 198

def archive(payment_method_id:)
  @http.post_resource(
    "/payment_methods/archive",
    Inttegro::PaymentMethod, :payment_method,
    { payment_method_id: payment_method_id }
  )
end

#confirm_verification(payload) ⇒ Inttegro::PaymentMethod

Submit the OTP received by the customer to complete payment method verification.

On success, the payment method's verified flag is set to true. Tokens expire after 8 minutes, and after 5 failed attempts, verification is locked—call verify() again to restart.

Examples:

Confirm verification with OTP

result = client.payment_methods.confirm_verification(
  payment_method_id: 'pm_xyz789',
  token: '123456'
)

if result.verified_at
  puts 'Payment method verified successfully!'
end

Parameters:

  • payload (Hash) —

    Confirmation parameters

Options Hash (payload):

  • :payment_method_id (String) —

    ID of the payment method being verified (required)

  • :token (String) —

    OTP code provided by customer (required, typically 6 digits)

Returns:

See Also:



111
112
113
114
115
116
117
 
# File 'lib/inttegro/resources/payment_methods.rb', line 111

def confirm_verification(payload)
  @http.post_resource(
    "/payment_methods/confirm_verification",
    Inttegro::PaymentMethod, :payment_method,
    payload
  )
end

#delete(payment_method_id:, request_meta: nil) ⇒ Inttegro::PaymentMethod::Deletion

Delete a saved payment method, removing it from the customer's account.

Permanently deletes the payment method. This action cannot be undone. Use when a customer requests removal of their payment details or when a payment method is no longer valid.

Examples:

Delete a payment method

result = client.payment_methods.delete(
  payment_method_id: 'pm_xyz789'
)

puts "Payment method deleted"

Parameters:

  • payment_method_id (String) —

    ID of the payment method to delete (required)

  • request_meta (Hash, nil) (defaults to: nil) —

    Request controls such as idempotency_key (optional)

Returns:

See Also:



236
237
238
239
240
241
242
243
 
# File 'lib/inttegro/resources/payment_methods.rb', line 236

def delete(payment_method_id:, request_meta: nil)
  @http.post_model("/payment_methods/delete", Inttegro::PaymentMethod::Deletion,
    {
      payment_method_id: payment_method_id,
      request_meta: request_meta || stable_payment_method_request_meta("delete", payment_method_id)
    }
  )
end

#disactivate(payment_method_id:) ⇒ Inttegro::PaymentMethod Also known as: deactivate

Mark an active payment method inactive.

Parameters:

  • payment_method_id (String) —

    unique payment method identifier

Returns:



184
185
186
187
188
189
190
 
# File 'lib/inttegro/resources/payment_methods.rb', line 184

def disactivate(payment_method_id:)
  @http.post_resource(
    "/payment_methods/disactivate",
    Inttegro::PaymentMethod, :payment_method,
    { payment_method_id: payment_method_id }
  )
end

#lookup(payment_method_id:) ⇒ Inttegro::PaymentMethod

Retrieve details of a saved payment method by its ID.

Returns full payment method information including type, verification status, and associated customer. Use this to display saved payment methods to customers or verify payment method status.

Examples:

Lookup a payment method

result = client.payment_methods.lookup(
  payment_method_id: 'pm_xyz789'
)

puts "Payment method type: #{result.type&.serialize}"

Parameters:

  • payment_method_id (String) —

    ID of the payment method to retrieve (required)

Returns:

See Also:



136
137
138
139
140
141
142
 
# File 'lib/inttegro/resources/payment_methods.rb', line 136

def lookup(payment_method_id:)
  @http.post_resource(
    "/payment_methods/lookup",
    Inttegro::PaymentMethod, :payment_method,
    { payment_method_id: payment_method_id }
  )
end

#page(payload = {}) ⇒ Inttegro::PaymentMethod::Page

Retrieve a page of payment methods.

Parameters:

Returns:



148
149
150
151
152
153
154
 
# File 'lib/inttegro/resources/payment_methods.rb', line 148

def page(payload = {})
  @http.post_resource(
    "/payment_methods/page",
    Inttegro::PaymentMethod::Page, :page,
    payload || {}
  )
end

#settings ⇒ Inttegro::PaymentMethod::Settings

Get configuration settings for payment methods in your application.

Returns settings that control payment method behavior, including whether verification is required before charging and supported payment method types.

Examples:

Get payment method settings

result = client.payment_methods.settings

puts "Mobile money enabled: #{result.mobile_money&.enabled}"

Returns:

See Also:



258
259
260
261
262
263
264
 
# File 'lib/inttegro/resources/payment_methods.rb', line 258

def settings
  @http.post_resource(
    "/payment_methods/settings",
    Inttegro::PaymentMethod::Settings, :settings,
    {}
  )
end

#tokenize(payload) ⇒ Inttegro::PaymentMethod

Save a new payment method for a customer without charging it.

Tokenizes and stores payment details for future use. Currently supports mobile money wallets. Use this to collect payment details during customer onboarding, let customers save multiple payment instruments, or set up payment methods before subscription billing.

After tokenization, you can optionally verify the payment method to confirm customer ownership and enable frictionless charging.

Examples:

Tokenize a mobile money payment method

result = client.payment_methods.tokenize(
  customer_id: 'cu_abc123',
  payment_method_data: {
    type: 'mobile_money',
    mobile_money: {
      network: 'mtn',
      account_number: '0544998605'
    }
  },
  verify_immediately: true
)

puts "Tokenized payment method: #{result.id}"

Parameters:

Options Hash (payload):

  • :customer_id (String) —

    Customer who will own this payment method (required)

  • :payment_method_data (Hash) —

    Payment method details (required)

  • :verify_immediately (Boolean) —

    Send verification OTP immediately (default: false)

Returns:

See Also:



51
52
53
54
55
56
57
 
# File 'lib/inttegro/resources/payment_methods.rb', line 51

def tokenize(payload)
  @http.post_resource(
    "/payment_methods/tokenize",
    Inttegro::PaymentMethod, :payment_method,
    payload
  )
end

#unarchive(payment_method_id:) ⇒ Inttegro::PaymentMethod

Restore an archived payment method so it can be updated again.

Parameters:

  • payment_method_id (String) —

    unique payment method identifier

Returns:



210
211
212
213
214
215
216
 
# File 'lib/inttegro/resources/payment_methods.rb', line 210

def unarchive(payment_method_id:)
  @http.post_resource(
    "/payment_methods/unarchive",
    Inttegro::PaymentMethod, :payment_method,
    { payment_method_id: payment_method_id }
  )
end

#update(payload) ⇒ Inttegro::PaymentMethod

Update mutable metadata on a payment method.

Parameters:

Returns:



160
161
162
163
164
165
166
 
# File 'lib/inttegro/resources/payment_methods.rb', line 160

def update(payload)
  @http.post_resource(
    "/payment_methods/update",
    Inttegro::PaymentMethod, :payment_method,
    payload
  )
end

#verify(payment_method_id:, request_meta: nil) ⇒ Inttegro::PaymentMethod::Verification

Send an OTP to confirm customer ownership of a payment method.

For mobile money, a 6-digit code is sent via SMS to the registered wallet number. The customer submits the token to complete verification. Verified payment methods can be charged without additional OTP confirmation, meet network provider requirements, and have better authorization rates.

Examples:

Verify a payment method

result = client.payment_methods.verify(
  payment_method_id: 'pm_xyz789'
)

puts "Verification request: #{result.request_id}"

Parameters:

  • payment_method_id (String) —

    ID of the payment method to verify (required)

  • request_meta (Hash, nil) (defaults to: nil) —

    Request controls such as idempotency_key (optional)

Returns:

See Also:



78
79
80
81
82
83
84
85
86
87
 
# File 'lib/inttegro/resources/payment_methods.rb', line 78

def verify(payment_method_id:, request_meta: nil)
  @http.post_resource(
    "/payment_methods/verify",
    Inttegro::PaymentMethod::Verification, :verification,
    {
      payment_method_id: payment_method_id,
      request_meta: request_meta || stable_payment_method_request_meta("verify", payment_method_id)
    }
  )
end