paystack_sdk 0.1.0 → 0.2.0

data/README.md

@@ -8,12 +8,21 @@ The `paystack_sdk` gem provides a simple and intuitive interface for interacting
 - [Quick Start](#quick-start)
 - [Usage](#usage)
   - [Client Initialization](#client-initialization)
+  - [Test and Live Keys](#test-and-live-keys)
   - [Transactions](#transactions)
     - [Initialize a Transaction](#initialize-a-transaction)
     - [Verify a Transaction](#verify-a-transaction)
     - [List Transactions](#list-transactions)
     - [Fetch a Transaction](#fetch-a-transaction)
     - [Get Transaction Totals](#get-transaction-totals)
+    - [Checking a Payment](#checking-a-payment)
+    - [Charging a Saved Card](#charging-a-saved-card)
+  - [Charges](#charges)
+    - [Mobile Money in Ghana: Which Networks](#mobile-money-in-ghana-which-networks)
+    - [Create a Mobile Money Charge](#create-a-mobile-money-charge)
+    - [Create a Charge on Another Channel](#create-a-charge-on-another-channel)
+    - [Complete a Charge](#complete-a-charge)
+    - [Check a Pending Charge](#check-a-pending-charge)
   - [Customers](#customers)
     - [Create a Customer](#create-a-customer)
     - [List Customers](#list-customers)
@@ -22,14 +31,27 @@ The `paystack_sdk` gem provides a simple and intuitive interface for interacting
     - [Validate a Customer](#validate-a-customer)
     - [Set Risk Action](#set-risk-action)
     - [Deactivate Authorization](#deactivate-authorization)
+  - [Banks](#banks)
+  - [Miscellaneous](#miscellaneous)
+  - [Transfer Recipients](#transfer-recipients)
+  - [Transfers](#transfers)
+    - [Initiate a Transfer](#initiate-a-transfer)
+    - [Verify, Fetch and List Transfers](#verify-fetch-and-list-transfers)
+    - [Bulk Transfers and the OTP Requirement](#bulk-transfers-and-the-otp-requirement)
+  - [Refunds](#refunds)
+    - [Create a Refund](#create-a-refund)
+    - [Fetch, List and Retry Refunds](#fetch-list-and-retry-refunds)
   - [Response Handling](#response-handling)
     - [Working with Response Objects](#working-with-response-objects)
     - [Accessing the Original Response](#accessing-the-original-response)
     - [Error Handling](#error-handling)
 - [Advanced Usage](#advanced-usage)
+  - [Timeouts and Retries](#timeouts-and-retries)
+  - [Webhooks](#webhooks)
   - [Environment Variables](#environment-variables)
   - [Direct Resource Instantiation](#direct-resource-instantiation)
 - [Development](#development)
+  - [Style and Linting](#style-and-linting)
 - [Contributing](#contributing)
 - [License](#license)
 - [Code of Conduct](#code-of-conduct)
@@ -63,14 +85,12 @@ require 'paystack_sdk'
 paystack = PaystackSdk::Client.new(secret_key: "sk_test_xxx")
 
 # Initialize a transaction
-params = {
-  email: "customer@email.com",
-  amount: 2300,  # Amount in the smallest currency unit (kobo for NGN)
-  currency: "NGN"
-}
-
 begin
-  response = paystack.transactions.initiate(params)
+  response = paystack.transactions.initiate(
+    email: "customer@email.com",
+    amount: 2300,  # Amount in the smallest currency unit (kobo for NGN)
+    currency: "NGN"
+  )
 
   if response.success?
     puts "Visit this URL to complete payment: #{response.authorization_url}"
@@ -78,21 +98,19 @@ begin
   else
     puts "Error: #{response.error_message}"
   end
-rescue PaystackSdk::MissingParamError => e
+rescue ArgumentError => e
   puts "Missing required data: #{e.message}"
 rescue PaystackSdk::InvalidFormatError => e
   puts "Invalid data format: #{e.message}"
 end
 
 # Create a customer
-customer_params = {
-  email: "customer@email.com",
-  first_name: "John",
-  last_name: "Doe"
-}
-
 begin
-  customer_response = paystack.customers.create(customer_params)
+  customer_response = paystack.customers.create(
+    email: "customer@email.com",
+    first_name: "John",
+    last_name: "Doe"
+  )
 
   if customer_response.success?
     puts "Customer created: #{customer_response.data.customer_code}"
@@ -121,10 +139,10 @@ The SDK validates your parameters **before** making API calls and throws excepti
 
 ```ruby
 begin
-  # This will throw an exception before making any API call
-  response = paystack.transactions.initiate({amount: 1000}) # Missing required email
-rescue PaystackSdk::MissingParamError => e
-  puts "Fix your data: #{e.message}"
+  # Ruby raises ArgumentError for a missing required keyword, before any API call
+  response = paystack.transactions.initiate(amount: 1000) # Missing required email
+rescue ArgumentError => e
+  puts "Fix your data: #{e.message}" # => "missing keyword: :email"
 end
 ```
 
@@ -133,7 +151,7 @@ end
 All successful API calls return a `Response` object that you can check for success:
 
 ```ruby
-response = paystack.transactions.initiate(valid_params)
+response = paystack.transactions.initiate(**valid_params)
 
 if response.success?
   puts "Transaction created: #{response.authorization_url}"
@@ -151,9 +169,9 @@ end
 
 - **Validation errors** - when required parameters are missing or have invalid formats
 - **Authentication errors** (401) - usually configuration issues
-- **Rate limiting** (429) - requires retry logic
+- **Rate limiting** (429) - raised after automatic retries are exhausted, or immediately if Paystack asks for a long wait (see [Timeouts and Retries](#timeouts-and-retries))
 - **Server errors** (5xx) - Paystack infrastructure issues
-- **Network errors** - connection failures
+- **Network errors** - timeouts and connection failures, raised as `PaystackSdk::TimeoutError` / `PaystackSdk::ConnectionError`
 
 All other API errors (resource not found, business logic errors, etc.) are returned as unsuccessful Response objects.
 
@@ -172,6 +190,19 @@ paystack = PaystackSdk::Client.new # => This will dynamically fetch the secret k
 connection = paystack.connection
 ```
 
+### Test and Live Keys
+
+A live key (`sk_live_...`) moves real money. `client.live?` tells you which kind a client holds, and `sandbox_only: true` makes the client refuse anything but a test key (`sk_test_...`) at construction, before any request is sent. Set it in staging and CI:
+
+```ruby
+client = PaystackSdk::Client.new(secret_key: ENV["PAYSTACK_SECRET_KEY"], sandbox_only: true)
+# => ArgumentError if the key is a live key, or anything not recognisable as a test key
+
+client.live? # => false
+```
+
+The error never includes the key. A pre-built Faraday connection is checked too (the key is read from its `Authorization` header).
+
 ### Transactions
 
 The SDK provides comprehensive support for Paystack's Transaction API.
@@ -179,16 +210,13 @@ The SDK provides comprehensive support for Paystack's Transaction API.
 #### Initialize a Transaction
 
 ```ruby
-# Prepare transaction parameters
-params = {
+# Amount is in the smallest currency unit (e.g., kobo, pesewas, cents)
+response = paystack.transactions.initiate(
   email: "customer@example.com",
-  amount: 10000,  # Amount in the smallest currency unit (e.g., kobo, pesewas, cents)
+  amount: 10000,
   currency: "GHS",
   callback_url: "https://example.com/callback"
-}
-
-# Initialize the transaction
-response = paystack.transactions.initiate(params)
+)
 
 if response.success?
   puts "Transaction initialized successfully!"
@@ -200,6 +228,113 @@ else
 end
 ```
 
+### Charges
+
+The Charge API lets you pick the payment channel yourself instead of sending the customer to Checkout: a saved card authorization, a bank account, USSD, mobile money, QR, EFT, Pay with Transfer or Capitec Pay. Many charges need one more step from the customer (a PIN, OTP, phone number, birthday or address) before they complete. See the Paystack docs: [Charge API](https://paystack.com/docs/api/charge/) and [Payment Channels](https://paystack.com/docs/payments/payment-channels/).
+
+#### Mobile Money in Ghana: Which Networks
+
+Paystack lists three Ghana mobile-money providers (`banks.list(country: "ghana", type: "mobile_money")`): `MTN`, `VOD` (shown as Vodafone, now Telecel) and `ATL` (AirtelTigo). The bank list uses uppercase codes; `charges.mobile_money` takes the provider in any case and sends it in lowercase (`mtn`, `vod`, `atl`).
+
+What was checked, against Paystack's test API only: a merchant-started charge of 100 pesewas (GHS) for each of the three providers on Paystack's test number was accepted, came back with `status: "success"` and `gateway_response: "Approved"` immediately, and `check_pending(reference:)` returned the same. **Test mode does not model the payer approving the prompt on their phone, so this does not show which live networks accept a charge you start yourself.** Treat each network as unverified in live mode: start the charge, read `response.status` (`status?(:pay_offline)`, `status?(:send_otp)`, `status?(:pending)` and so on, as Paystack returns them), show `response.display_text` to the payer when there is one, and poll `charges.check_pending(reference:)` or wait for the `charge.success` webhook. Confirm with `transactions.verify(reference:)` before giving value. If a network refuses a merchant-started prompt, fall back to a payment link for that network.
+
+#### Create a Mobile Money Charge
+
+Mobile money is available to businesses in Ghana, Kenya and Côte d'Ivoire. `mobile_money` checks the `mobile_money` object (phone or till account, and a known provider) and sends it with `create`.
+
+Supported providers (case-insensitive): `mtn`, `atl` (ATMoney/Airtel Money), `vod` (Telecel, formerly Vodafone), `mpesa`, `mpesa_offline`, `mptill` (M-PESA Till: send `account:`, the till number, instead of `phone:`), `orange`, `wave`.
+
+```ruby
+paystack = PaystackSdk::Client.new(secret_key: "sk_test_xxx")
+
+response = paystack.charges.mobile_money(
+  email: "customer@email.com",
+  amount: 100,             # smallest unit (pesewas/cent)
+  currency: "GHS",         # optional; Paystack uses your integration's currency without it
+  mobile_money: {
+    phone: "0551234987",
+    provider: "mtn"        # mtn | atl | vod | mpesa | mpesa_offline | mptill | orange | wave
+  }
+)
+
+if response.success?
+  case response.status
+  when "pay_offline"
+    # Show instruction text and wait for webhook or verify later
+    puts response.display_text
+  when "send_otp"
+    # For Vodafone, collect voucher/OTP and submit below
+    puts response.display_text
+  when "success"
+    puts "Charge completed: #{response.reference}"
+  else
+    puts "Status: #{response.status}"
+  end
+else
+  puts "Charge failed: #{response.error_message}"
+end
+```
+
+#### Create a Charge on Another Channel
+
+`create` takes one channel object (or an `authorization_code`) as a keyword hash and sends it as Paystack documents it.
+
+```ruby
+# A returning customer's saved card
+paystack.charges.create(email: "customer@email.com", amount: 10000, authorization_code: "AUTH_xxxx")
+
+# A bank account (Paystack may then ask for the customer's birthday or an OTP)
+paystack.charges.create(
+  email: "customer@email.com",
+  amount: 10000,
+  bank: {code: "057", account_number: "0000000000"},
+  birthday: Date.new(1995, 12, 23) # or "1995-12-23"
+)
+
+# USSD (Nigeria), Pay with Transfer, and QR or EFT (South Africa)
+paystack.charges.create(email: "customer@email.com", amount: 10000, ussd: {type: "737"})
+paystack.charges.create(email: "customer@email.com", amount: 10000, bank_transfer: {account_expires_at: "2026-10-10T12:00:00Z"})
+paystack.charges.create(email: "customer@email.com", amount: 10000, currency: "ZAR", qr: {provider: "scan-to-pay"})
+paystack.charges.create(email: "customer@email.com", amount: 10000, currency: "ZAR", eft: {provider: "ozow"})
+
+# Send the payment through a split or to a subaccount
+paystack.charges.create(email: "customer@email.com", amount: 10000, authorization_code: "AUTH_xxxx", split_code: "SPL_xxxx")
+```
+
+#### Complete a Charge
+
+When the response asks for more from the customer (read `response.status` and `response.display_text`), send it with the charge's `reference`:
+
+```ruby
+paystack.charges.submit_pin(pin: "1234", reference: "5bwib5v6anhe9xa")
+paystack.charges.submit_otp(otp: "123456", reference: "5bwib5v6anhe9xa") # e.g. a Vodafone voucher
+paystack.charges.submit_phone(phone: "08012345678", reference: "5bwib5v6anhe9xa")
+paystack.charges.submit_birthday(birthday: "1961-09-21", reference: "5bwib5v6anhe9xa")
+paystack.charges.submit_address(
+  address: "140 N 2ND ST",
+  city: "Stroudsburg",
+  state: "PA",
+  zip_code: "18360",
+  reference: "7c7rpkqpc0tijs8"
+)
+```
+
+#### Check a Pending Charge
+
+If a charge comes back `pending`, or a `/charge` call failed with an exception, wait at least 10 seconds, then check it (Paystack warns that checking too early returns more `pending` results):
+
+```ruby
+response = paystack.charges.check_pending(reference: "5bwib5v6anhe9xa")
+puts response.status
+```
+
+For offline flows such as mobile money, listen for the `charge.success` webhook, and confirm it with `transactions.verify(reference:)` before giving value:
+
+```ruby
+verify = paystack.transactions.verify(reference: "r13havfcdt7btcm")
+puts verify.status # "success", "failed", or current state
+```
+
 #### Verify a Transaction
 
 ```ruby
@@ -231,7 +366,7 @@ end
 #### List Transactions
 
 ```ruby
-# Get all transactions (default pagination: 50 per page)
+# Get all transactions (Paystack's default pagination: 50 per page)
 response = paystack.transactions.list
 
 # With custom pagination
@@ -246,6 +381,9 @@ response = paystack.transactions.list(
   status: "success"
 )
 
+# Filter by customer (the numeric customer ID, not the CUS_ code)
+response = paystack.transactions.list(customer_id: 12345)
+
 if response.success?
   puts "Total transactions: #{response.count}" # response.size is another way
 
@@ -272,8 +410,7 @@ end
 
 ```ruby
 # Fetch a specific transaction by ID
-transaction_id = "12345"
-response = paystack.transactions.fetch(transaction_id)
+response = paystack.transactions.fetch(id: 12345)
 
 if response.success?
   transaction = response.data
@@ -297,6 +434,9 @@ end
 # Get transaction volume and success metrics
 response = paystack.transactions.totals
 
+# Within a date range
+response = paystack.transactions.totals(from: "2025-01-01", to: "2025-04-30")
+
 if response.success?
   puts "Total Transactions: #{response.data.total_transactions}"
   puts "Total Volume: #{response.data.total_volume}"
@@ -306,23 +446,79 @@ else
 end
 ```
 
+#### Transaction Timeline, Export and Charging
+
+```ruby
+# Timeline of a transaction, by ID or reference
+paystack.transactions.timeline(id: "transaction_reference")
+
+# Export transactions (Paystack returns a download link)
+paystack.transactions.export(from: "2025-01-01", to: "2025-04-30", status: "success", settled: true)
+
+# Charge a returning customer's saved authorization
+paystack.transactions.charge_authorization(
+  email: "customer@example.com",
+  amount: 10000,
+  authorization_code: "AUTH_xxxx"
+)
+
+# Debit part of an amount from a saved authorization
+paystack.transactions.partial_debit(
+  email: "customer@example.com",
+  amount: 5000,
+  authorization_code: "AUTH_xxxx",
+  currency: "GHS"
+)
+```
+
+#### Checking a Payment
+
+Confirm a payment by verifying it, then check the status, amount and currency. `paid?` does all three: it is true only when the call succeeded and the transaction's `status` is `"success"`, and, for the `amount` and `currency` you pass, they match what Paystack reports.
+
+```ruby
+response = paystack.transactions.verify(reference: reference)
+
+if response.paid?(amount: 5000, currency: "GHS") # amount in the smallest unit, e.g. pesewas
+  authorization = response.authorization
+  authorization.authorization_code # keep this to charge the card again
+  authorization.reusable           # true if it can be charged again
+end
+```
+
+Fields keep Paystack's own names: `response.reference`, `amount`, `currency`, `status`, `paid_at`, `gateway_response`, `fees`, `customer.email`, `customer.customer_code`, and on `authorization`: `authorization_code`, `reusable`, `channel`, `last4`, `card_type`, `signature`, `exp_month`, `exp_year`, `bin`, `bank`, `account_name`, `country_code` and `brand`. `response.status?(:pending)` compares the `status` field with any value, which is how you read a charge that is waiting on the payer (`status?(:send_pin)`, `status?(:pay_offline)`); `response.display_text` is the prompt Paystack wants shown to them.
+
+#### Charging a Saved Card
+
+After a successful card payment, the `authorization_code` can be charged again with no checkout, for example for a renewal. Only an authorization with `reusable: true` can be charged again.
+
+```ruby
+charge = paystack.transactions.charge_authorization(
+  email: "customer@example.com",   # the customer the authorization belongs to
+  amount: 5000,
+  currency: "GHS",
+  authorization_code: "AUTH_xxxx",
+  reference: "renewal-2025-06-ama"  # unique per attempt; reuse it if you retry so you cannot charge twice
+)
+
+paystack.transactions.verify(reference: "renewal-2025-06-ama").paid?(amount: 5000, currency: "GHS")
+```
+
+This was checked against Paystack's test API: a reusable card authorization charged successfully (`status: "success"`, `gateway_response: "Approved"`), and an unknown `authorization_code` came back as an unsuccessful response with `"Authorization code is invalid"`. Writes are never retried after a timeout, so if a `charge_authorization` call times out, verify the `reference` before charging again. Test mode does not prove live behaviour.
+
 ### Customers
 
-The SDK provides comprehensive support for Paystack's Customer API, allowing you to manage customer records and their associated data.
+The SDK provides comprehensive support for Paystack's Customer API, allowing you to manage customer records, their identity validation, risk actions and authorizations (including Direct Debit mandates).
 
 #### Create a Customer
 
 ```ruby
-# Prepare customer parameters
-params = {
+response = paystack.customers.create(
   email: "customer@example.com",
   first_name: "John",
   last_name: "Doe",
-  phone: "+2348123456789"
-}
-
-# Create the customer
-response = paystack.customers.create(params)
+  phone: "+2348123456789",
+  metadata: {plan: "gold"} # a Hash; Paystack rejects a JSON string here
+)
 
 if response.success?
   puts "Customer created successfully!"
@@ -334,10 +530,12 @@ else
 end
 ```
 
+`first_name`, `last_name` and `phone` are optional, except for customers you will assign a Dedicated Virtual Account to in some business categories (see Paystack's docs).
+
 #### List Customers
 
 ```ruby
-# Get all customers (default pagination: 50 per page)
+# Get all customers (Paystack's default pagination: 50 per page)
 response = paystack.customers.list
 
 # With custom pagination
@@ -351,8 +549,12 @@ response = paystack.customers.list(
   to: "2025-06-10"
 )
 
+# Cursor pagination: the cursors come back in response.meta
+response = paystack.customers.list(use_cursor: true, per_page: 20)
+response = paystack.customers.list(use_cursor: true, per_page: 20, next_cursor: response.meta.next)
+
 if response.success?
-  puts "Total customers: #{response.data.size}"
+  puts "Customers on this page: #{response.data.size}"
 
   response.data.each do |customer|
     puts "Code: #{customer.customer_code}"
@@ -369,11 +571,10 @@ end
 
 ```ruby
 # Fetch by customer code
-customer_code = "CUS_xr58yrr2ujlft9k"
-response = paystack.customers.fetch(customer_code)
+response = paystack.customers.fetch(email_or_code: "CUS_xr58yrr2ujlft9k")
 
-# Or fetch by email
-response = paystack.customers.fetch("customer@example.com")
+# Or fetch by email (Paystack accepts either in the same place)
+response = paystack.customers.fetch(email_or_code: "customer@example.com")
 
 if response.success?
   customer = response.data
@@ -390,14 +591,12 @@ end
 #### Update a Customer
 
 ```ruby
-customer_code = "CUS_xr58yrr2ujlft9k"
-update_params = {
+response = paystack.customers.update(
+  code: "CUS_xr58yrr2ujlft9k",
   first_name: "Jane",
   last_name: "Smith",
   phone: "+2348987654321"
-}
-
-response = paystack.customers.update(customer_code, update_params)
+)
 
 if response.success?
   puts "Customer updated successfully!"
@@ -409,19 +608,19 @@ end
 
 #### Validate a Customer
 
+Paystack only supports `type: "bank_account"` for now, and requires every keyword below; `middle_name` and `value` are optional. Paystack answers `202` and completes the validation asynchronously.
+
 ```ruby
-customer_code = "CUS_xr58yrr2ujlft9k"
-validation_params = {
-  country: "NG",
+response = paystack.customers.validate(
+  code: "CUS_xr58yrr2ujlft9k",
+  first_name: "John",
+  last_name: "Doe",
   type: "bank_account",
-  account_number: "0123456789",
+  country: "NG",
   bvn: "20012345677",
   bank_code: "007",
-  first_name: "John",
-  last_name: "Doe"
-}
-
-response = paystack.customers.validate(customer_code, validation_params)
+  account_number: "0123456789"
+)
 
 if response.success?
   puts "Customer validation initiated: #{response.message}"
@@ -430,15 +629,14 @@ else
 end
 ```
 
-#### Set Risk Action
+#### Set Risk Action (Whitelist/Blacklist)
 
 ```ruby
-params = {
+# customer: the customer code or email address
+response = paystack.customers.set_risk_action(
   customer: "CUS_xr58yrr2ujlft9k",
-  risk_action: "allow"  # Options: "default", "allow", "deny"
-}
-
-response = paystack.customers.set_risk_action(params)
+  risk_action: "allow" # "allow" to whitelist, "deny" to blacklist, "default" to reset
+)
 
 if response.success?
   puts "Risk action set successfully!"
@@ -449,14 +647,35 @@ else
 end
 ```
 
-#### Deactivate Authorization
+#### Authorizations and Direct Debit
 
 ```ruby
-params = {
-  authorization_code: "AUTH_72btv547"
-}
+# Start creating a reusable authorization (direct_debit is the only channel for now)
+response = paystack.customers.initialize_authorization(
+  email: "customer@example.com",
+  channel: "direct_debit",
+  callback_url: "https://example.com/callback"
+)
+reference = response.data.reference # send the customer to response.data.redirect_url
 
-response = paystack.customers.deactivate_authorization(params)
+# Check the authorization's status
+paystack.customers.verify_authorization(reference: reference)
+
+# Link a bank account to an existing customer for Direct Debit (id is the numeric customer ID)
+paystack.customers.initialize_direct_debit(
+  id: 12345,
+  account: {number: "0123456789", bank_code: "058"},
+  address: {street: "Some Where", city: "Ikeja", state: "Lagos"}
+)
+
+# The customer's Direct Debit mandates
+paystack.customers.fetch_mandate_authorizations(id: 12345)
+
+# Trigger an activation charge on an inactive mandate
+paystack.customers.direct_debit_activation_charge(id: 12345, authorization_id: 1069309917)
+
+# Deactivate an authorization (any channel)
+response = paystack.customers.deactivate_authorization(authorization_code: "AUTH_72btv547")
 
 if response.success?
   puts "Authorization deactivated: #{response.message}"
@@ -465,6 +684,217 @@ else
 end
 ```
 
+### Banks
+
+Everything takes keyword arguments. Account numbers and bank codes are strings, so leading zeros survive.
+
+```ruby
+# List banks. Filters are optional: country (ghana, kenya, nigeria, "south africa"), currency,
+# type, gateway, per_page, page, use_cursor, next_cursor, previous, ...
+response = paystack.banks.list(country: "nigeria", per_page: 50)
+response.data.each { |bank| puts "#{bank["name"]}: #{bank["code"]}" }
+
+# Resolve an account number to the name on the account
+response = paystack.banks.resolve_account_number(account_number: "0022728151", bank_code: "063")
+puts response.data["account_name"] if response.success?
+
+# Validate a South African bank account before sending money
+response = paystack.banks.validate_account(
+  account_name: "Ama Mensah",
+  account_number: "0123456789",
+  account_type: "personal",
+  bank_code: "632005",
+  country_code: "ZA",
+  document_type: "identityNumber",
+  document_number: "1234567890123" # optional
+)
+```
+
+### Miscellaneous
+
+```ruby
+# Details of a card BIN (6 or 8 digits, as a string)
+response = paystack.miscellaneous.resolve_card_bin(bin: "539983")
+puts response.data["bank"] if response.success?
+
+# Supported countries
+paystack.miscellaneous.list_countries
+
+# States for address verification (country is required)
+paystack.miscellaneous.list_states(country: "CA")
+```
+
+### Transfer Recipients
+
+Every method takes keyword arguments. A recipient is who you send a transfer to.
+
+#### Create a Transfer Recipient
+
+```ruby
+response = paystack.transfer_recipients.create(
+  type: "nuban", # nuban, ghipss, mobile_money, basa or authorization
+  name: "Ama Mensah",
+  account_number: "0123456789",
+  bank_code: "058",
+  currency: "NGN",
+  metadata: {job: "Baker"}
+)
+
+puts response.data.recipient_code if response.success?
+```
+
+A duplicate account number returns the existing recipient. To create many at once, pass a list of recipient hashes:
+
+```ruby
+response = paystack.transfer_recipients.bulk_create(
+  batch: [
+    {type: "nuban", name: "Ama Mensah", account_number: "0123456789", bank_code: "058"},
+    {type: "nuban", name: "Kofi Boateng", account_number: "0987654321", bank_code: "058"}
+  ]
+)
+
+response.data.success # recipients that were created
+response.data.errors  # records Paystack rejected, with the reason
+```
+
+#### List, Fetch, Update and Delete
+
+```ruby
+paystack.transfer_recipients.list(per_page: 20, page: 2)
+
+# fetch, update and delete take the recipient code or the numeric ID
+paystack.transfer_recipients.fetch(id_or_code: "RCP_2x5j67tnnw1t98k")
+paystack.transfer_recipients.update(id_or_code: "RCP_2x5j67tnnw1t98k", name: "Ama K. Mensah", email: "ama@example.com")
+paystack.transfer_recipients.delete(id_or_code: "RCP_2x5j67tnnw1t98k") # Paystack sets the recipient to inactive
+```
+
+Paystack's docs list `from` and `to` filters on the list endpoint, but the API ignores them (checked against the test API), so the SDK does not offer them. Cursor pagination is available with `use_cursor: true`, `next_cursor:` and `previous:`.
+
+### Transfers
+
+Transfers send money from your Paystack balance to a transfer recipient (`RCP_...`). They move real money in live mode, so the SDK never retries them except on `429` (see [Timeouts and Retries](#timeouts-and-retries)).
+
+#### Initiate a Transfer
+
+```ruby
+# Amount is in the smallest currency unit (kobo, pesewas, cents).
+# reference is required: generate it once and reuse it if you retry, so a retry cannot pay twice.
+# Paystack documents 16 to 50 characters of lowercase letters, digits, - and _.
+response = paystack.transfers.create(
+  source: "balance",
+  amount: 100_000,
+  recipient: "RCP_gd9vgag7n5lr5ix",
+  reference: "acv_9ee55786-2323-4760-98e2-6380c9cb3f68",
+  reason: "Bonus for the week"
+)
+
+if response.success?
+  case response.data.status
+  when "otp"
+    # Your integration requires an OTP: Paystack sent one to the business phone
+    paystack.transfers.finalize(transfer_code: response.data.transfer_code, otp: "928783")
+  else
+    puts "Transfer #{response.data.transfer_code} is #{response.data.status}"
+  end
+else
+  puts "Error: #{response.error_message}"
+end
+```
+
+#### Verify, Fetch and List Transfers
+
+```ruby
+# Verify by your reference
+paystack.transfers.verify(reference: "acv_9ee55786-2323-4760-98e2-6380c9cb3f68")
+
+# Fetch by transfer ID or code
+paystack.transfers.fetch(id_or_code: "TRF_v5tip3zx8nna9o78")
+
+# List, with Paystack's page pagination (default 50 per page)...
+paystack.transfers.list(per_page: 20, page: 2, from: "2025-01-01", to: "2025-04-30")
+
+# ...filtered by the numeric recipient ID, or by status
+paystack.transfers.list(recipient: 56824902, status: "success")
+
+# ...or with cursor pagination: pass response.meta.next back as next_cursor
+paystack.transfers.list(use_cursor: true, per_page: 20)
+
+# Export transfers (in Paystack's OpenAPI spec, not on its docs page)
+paystack.transfers.export(from: "2025-01-01", to: "2025-04-30", status: "success")
+```
+
+#### Bulk Transfers and the OTP Requirement
+
+```ruby
+# Bulk transfers need the OTP requirement disabled. Each transfer uses Paystack's field names.
+paystack.transfers.bulk_create(
+  source: "balance",
+  currency: "NGN",
+  transfers: [
+    {amount: 20_000, recipient: "RCP_gd9vgag7n5lr5ix", reference: "acv_2627bbfe-1a2a-4a1a-8d0e-9d2ee6c31496", reason: "Bonus"},
+    {amount: 35_000, recipient: "RCP_zpk2tgagu6lgb4g", reference: "acv_1bd0c1f8-78c2-463b-8bd4-ed9eeb36be50", reason: "Bonus"}
+  ]
+)
+
+# Turn the OTP requirement off (Paystack sends an OTP to the business phone), then confirm it
+paystack.transfers.disable_otp
+paystack.transfers.finalize_disable_otp(otp: "928783")
+
+# Turn it back on
+paystack.transfers.enable_otp
+
+# Resend the OTP for a transfer awaiting one
+paystack.transfers.resend_otp(transfer_code: "TRF_vsyqdmlzble3uii", reason: "resend_otp")
+```
+
+### Refunds
+
+Refunds return money from a successful transaction to the customer. They move real money in live mode, so the SDK never retries them except on `429` (see [Timeouts and Retries](#timeouts-and-retries)).
+
+#### Create a Refund
+
+```ruby
+# transaction is the transaction's reference or its numeric ID.
+# amount is in the smallest currency unit (kobo, pesewas, cents) and cannot exceed the transaction amount.
+# Leave amount out to refund the whole transaction; pass less for a partial refund.
+response = paystack.refunds.create(
+  transaction: "T685312322670591",
+  amount: 2_500,
+  currency: "GHS",               # optional; Paystack refuses one that differs from the transaction's
+  customer_note: "Duplicate payment",
+  merchant_note: "Refunded by the finance team"
+)
+
+if response.success?
+  puts "Refund #{response.data.id} is #{response.data.status}" # "pending" until Paystack processes it
+else
+  puts "Error: #{response.error_message}" # e.g. "Transaction not found"
+end
+
+# A full refund by transaction ID
+paystack.refunds.create(transaction: 1_004_723_697)
+```
+
+#### Fetch, List and Retry Refunds
+
+```ruby
+paystack.refunds.fetch(id: 18_625_648)
+
+# List, with page pagination (default 50 per page) and a date range...
+paystack.refunds.list(per_page: 20, page: 1, from: "2025-01-01", to: "2025-04-30")
+
+# ...or the refunds of one transaction, by its numeric ID (a reference returns none)
+paystack.refunds.list(transaction_id: 1_004_723_697)
+
+# Retry a refund with the needs-attention status by giving the customer's bank account
+paystack.refunds.retry_with_customer_details(
+  id: 18_625_648,
+  refund_account_details: {currency: "GHS", account_number: "0123456789", bank_id: "9"}
+)
+```
+
+Paystack's docs also list a `currency` filter on the list endpoint, but the test API returned the same refunds for every currency, so the SDK does not offer it.
+
 ### Response Handling
 
 #### Working with Response Objects
@@ -472,7 +902,7 @@ end
 All API requests return a `PaystackSdk::Response` object that provides easy access to the response data.
 
 ```ruby
-response = paystack.transactions.initiate(params)
+response = paystack.transactions.initiate(**params)
 
 # Check if the request was successful
 response.success?  # => true or false
@@ -490,6 +920,12 @@ response.authorization_url  # Same as response.data.authorization_url
 # Access nested data
 response.data.customer.email
 
+# Hash-style access works with strings or symbols
+response[:reference]
+response["reference"]
+response[:customer][:email]
+response.key?(:reference)  # => true
+
 # For arrays, use array methods
 response.data.first  # First item in an array
 response.data.last   # Last item in an array
@@ -501,6 +937,21 @@ response.data.each do |item|
 end
 ```
 
+#### Pagination Metadata
+
+List responses carry Paystack's pagination details in `meta`:
+
+```ruby
+response = paystack.transactions.list(per_page: 20)
+
+response.meta.total      # => 40
+response.meta.page       # => 1
+response.meta.pageCount  # => 2
+response.meta.perPage    # => 20
+```
+
+`response.meta` is `nil` when the response has no `meta`.
+
 #### Accessing the Original Response
 
 Sometimes you may need access to the original API response:
@@ -511,9 +962,8 @@ response = paystack.transactions.list
 # Access the original response body
 original = response.original_response
 
-# Access metadata from the original response
-total_count = original.dig("meta", "total")
-current_page = original.dig("meta", "page")
+# Anything else in the body is still reachable
+original.dig("meta", "total")
 ```
 
 #### Exception Handling
@@ -526,9 +976,14 @@ begin
 rescue PaystackSdk::AuthenticationError => e
   puts "Authentication failed: #{e.message}"
 rescue PaystackSdk::RateLimitError => e
-  puts "Rate limit exceeded. Retry after: #{e.retry_after} seconds"
+  # retry_after is nil when Paystack did not send x-ratelimit-reset
+  puts "Rate limit exceeded. Retry after: #{e.retry_after || "unknown"} seconds"
 rescue PaystackSdk::ServerError => e
   puts "Server error: #{e.message}"
+rescue PaystackSdk::TimeoutError, PaystackSdk::ConnectionError => e
+  # For writes (e.g. creating a transfer) the request may still have been processed:
+  # verify by your own reference before retrying
+  puts "Could not complete the request: #{e.message}"
 rescue PaystackSdk::APIError => e
   puts "API error: #{e.message}"
 rescue PaystackSdk::Error => e
@@ -566,36 +1021,39 @@ The SDK includes several specific error classes:
   - **`PaystackSdk::RateLimitError`** - Rate limiting encountered
   - **`PaystackSdk::ServerError`** - Server errors (5xx responses)
 
+- **`PaystackSdk::ConnectionError`** - Could not reach Paystack (DNS, refused connection, TLS) after retries
+  - **`PaystackSdk::TimeoutError`** - The request timed out after retries
+
 ##### Validation Error Examples
 
 The SDK validates your input data **before** making API calls and will throw exceptions immediately if required data is missing or incorrectly formatted:
 
 ```ruby
-# Missing required parameter
+# Missing required keyword
 begin
-  paystack.transactions.initiate({amount: 1000}) # Missing email
-rescue PaystackSdk::MissingParamError => e
-  puts e.message # => "Missing required parameter: email"
+  paystack.transactions.initiate(amount: 1000) # Missing email
+rescue ArgumentError => e
+  puts e.message # => "missing keyword: :email"
 end
 
 # Invalid format
 begin
-  paystack.transactions.initiate({
+  paystack.transactions.initiate(
     email: "invalid-email",  # Not a valid email format
     amount: 1000
-  })
+  )
 rescue PaystackSdk::InvalidFormatError => e
   puts e.message # => "Invalid format for Email. Expected format: valid email address"
 end
 
 # Invalid value
 begin
-  paystack.customers.set_risk_action({
+  paystack.customers.set_risk_action(
     customer: "CUS_123",
     risk_action: "invalid_action"  # Not in allowed values
-  })
+  )
 rescue PaystackSdk::InvalidValueError => e
-  puts e.message # => "Invalid value for risk_action: must be one of [default, allow, deny]"
+  puts e.message # => "Invalid value for risk_action: must be one of: allow, deny, default"
 end
 ```
 
@@ -603,6 +1061,68 @@ These validation errors are thrown immediately and prevent the API call from bei
 
 ## Advanced Usage
 
+### Timeouts and Retries
+
+Connections built by the SDK time out and retry transient failures by default:
+
+```ruby
+client = PaystackSdk::Client.new(
+  secret_key: "sk_test_xxx",
+  timeout: 30,        # seconds to wait for a response
+  open_timeout: 5,    # seconds to wait for the connection to open
+  max_retries: 2,     # retries after the first attempt (0 disables retrying)
+  retry_interval: 0.5 # base backoff in seconds, doubled on each retry with jitter
+)
+```
+
+- Read-only requests (`GET`) are retried on network failures and `429`/`502`/`503`/`504` responses.
+- Anything that writes (`POST`, `PUT`, `DELETE`) is retried **only on `429`**, where Paystack rejected the
+  request for exceeding the rate limit. A timeout or `5xx` on a write may mean Paystack processed it, so it is
+  not retried. Pass `retry_non_idempotent: true` only if you deduplicate yourself (e.g. verify by reference first).
+- On a `429` the SDK waits for Paystack's `x-ratelimit-reset` header (seconds) before retrying. If the wait
+  exceeds 10 seconds it stops retrying and raises `PaystackSdk::RateLimitError` (`#retry_after` holds the value).
+- Errors that survive all retries are raised as `PaystackSdk::RateLimitError`, `PaystackSdk::ServerError`,
+  `PaystackSdk::TimeoutError` or `PaystackSdk::ConnectionError`, all of which inherit from `PaystackSdk::Error`.
+- These options only apply to connections the SDK creates. Passing them together with your own `Faraday::Connection` raises `ArgumentError`; configure your connection yourself. Invalid values (e.g. a negative `max_retries`) also raise `ArgumentError`.
+
+### Webhooks
+
+Paystack tells you about changes (a charge succeeded, a refund was processed, a transfer failed) by POSTing events to your webhook URL. `PaystackSdk::Webhook` verifies and parses them, and works with any framework.
+
+Paystack signs each event: the `x-paystack-signature` header is a lowercase hex HMAC SHA512 of the **raw request body**, using your secret key. Verify it before using the event.
+
+```ruby
+# Rails controller (skip CSRF protection for this action)
+def create
+  event = PaystackSdk::Webhook.construct_event(
+    payload: request.raw_post,                          # raw body, not params
+    signature: request.headers["X-Paystack-Signature"],
+    secret: ENV.fetch("PAYSTACK_SECRET_KEY")
+  )
+
+  HandlePaystackEventJob.perform_later(event.payload)   # do the work in the background
+  head :ok                                              # acknowledge quickly
+rescue PaystackSdk::WebhookError
+  head :bad_request
+end
+```
+
+```ruby
+event.event             # => "charge.success"
+event.data.reference    # data is wrapped like any Response
+event.data[:amount]
+event.known?            # => true if Paystack documents this event name
+event.payload           # the parsed JSON Hash (string keys), handy for queuing a job
+```
+
+- `Webhook.valid_signature?(payload:, signature:, secret:)` returns a boolean, and `Webhook.verify!` raises `PaystackSdk::InvalidSignatureError`. The comparison is constant-time.
+- The payload must be the exact bytes received. A parsed or re-serialised body will not match, and a non-String payload raises `ArgumentError`. A blank secret also raises, rather than checking against nothing.
+- `Webhook.construct_event` verifies first and parses only afterwards. A signed body that is not a JSON event raises `PaystackSdk::InvalidPayloadError`. Events Paystack adds later still come back, with `known?` false.
+- `Webhook.trusted_ip?(ip)` checks the three addresses Paystack documents (`Webhook::IP_ADDRESSES`). Use it as an extra check, not instead of the signature.
+- `Webhook.sign(payload, secret)` produces a valid signature, for testing your own endpoint.
+- Paystack retries events your server does not acknowledge with a `200 OK`: in live mode every 3 minutes for 4 tries, then hourly for 72 hours. Return `200` fast, process in a background job, and make handlers safe to run more than once.
+- Before giving value for a `charge.success`, confirm it with `transactions.verify(reference:)`, as Paystack recommends.
+
 ### Environment Variables
 
 You can use environment variables to configure the SDK:
@@ -641,11 +1161,29 @@ For more detailed documentation on specific resources, please refer to the follo
 - [Customers](https://paystack.com/docs/api/customer/)
 - [Plans](https://paystack.com/docs/api/plan/)
 - [Subscriptions](https://paystack.com/docs/api/subscription/)
+- [Payment Channels: Mobile Money](https://paystack.com/docs/payments/payment-channels/#mobile-money)
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
+### Style and Linting
+
+This project uses [StandardRB](https://github.com/standardrb/standard) for code style and linting.
+
+Add to your Gemfile (if not already present):
+
+```ruby
+gem "standard"
+```
+
+- Lint: `bundle exec standardrb`
+- Auto-fix: `bundle exec standardrb --fix`
+- Via Rake: `bundle exec rake standard`
+- Default task (runs specs + standard): `bundle exec rake`
+
+If you encounter cache permission issues locally, you can disable caching: `bundle exec standardrb --no-cache`.
+
 ### Testing
 
 The SDK includes comprehensive test coverage with consistent response format handling. All test specifications use string keys with hashrocket notation (`=>`) to match the actual format returned by the Paystack API:
@@ -667,7 +1205,7 @@ Tests also validate specific error types to ensure proper exception handling:
 
 ```ruby
 # Testing specific error types
-expect { customers.set_risk_action(invalid_params) }
+expect { customers.set_risk_action(customer: "CUS_123", risk_action: "block") }
   .to raise_error(PaystackSdk::InvalidValueError, /risk_action/i)
 ```