Finswitz Ruby SDK

Ruby client for the Finswitz API.

Installation

The Ruby SDK is currently distributed as a source client. Add finswitz.rb to your application and require it from your server-side code.

When a gem is published, this README should be updated with the gem install command.

Requirements

• Ruby 3.0 or newer
• A Finswitz test or live secret key

Quick Start

require_relative "finswitz"

client = Finswitz::Client.new(api_key: ENV.fetch("FINSWITZ_SECRET_KEY"))

link = client.create_payment_link(
  {
    amount: 5000,
    currency: "NGN",
    title: "Order #1234",
    email: "buyer@example.com",
    callback_url: "https://merchant.example/complete"
  },
  idempotency_key: "order-1234-link"
)

puts link["checkoutUrl"]

Custom Base URL

client = Finswitz::Client.new(
  api_key: ENV.fetch("FINSWITZ_SECRET_KEY"),
  base_url: "http://localhost:4000"
)

Payments

client.transfer(
  {
    amount: 5000,
    currency: "NGN",
    bank_code: "058",
    account_number: "0123456789",
    narration: "Vendor payout"
  },
  idempotency_key: "transfer-001"
)

client.mobile_money(
  {
    amount: 1500,
    currency: "GHS",
    phone: "+233501112222",
    country: "GH"
  },
  idempotency_key: "momo-001"
)

transaction = client.get_transaction("reference")

Dashboard JWT Helpers

client = Finswitz::Client.new(
  api_key: ENV.fetch("FINSWITZ_SECRET_KEY"),
  dashboard_token: ENV.fetch("FINSWITZ_DASHBOARD_TOKEN")
)

client.update_webhooks({
  mode: "test",
  url: "https://merchant.example/webhooks/finswitz"
})

wallets = client.wallets
treasury = client.treasury

Collections

collection = client.public_collection("school-fees")

payment = client.pay_collection(
  "school-fees",
  {
    fullName: "Grace Johnson",
    email: "grace@example.com",
    amount: 10000,
    phone: "+2348012345678"
  }
)

Error Handling

begin
  client.get_transaction("missing-reference")
rescue Finswitz::ApiError => error
  warn error.status
  warn error.response
  raise
end