Ruby

The sanwo gem provides a standalone client and a Rails view helper for rendering Sanwo checkout buttons and custom amount forms.

Installation

gem

gem install sanwo

Bundler

# Gemfile
gem "sanwo"

Standalone usage

Use the Sanwo::Client directly in any Ruby application:

require "sanwo"

client = Sanwo::Client.new(
  provider: Sanwo::Providers::PAYSTACK,
  public_key: "pk_test_xxxxx",
  currency: "NGN",
)

# Render the CDN script tag (once per page)
script_tag = client.render_script

# Render a checkout button
button_html = client.render_checkout(
  amount: 500_000,
  email: "customer@example.com",
  button_text: "Pay ₦5,000",
)

# Render a custom amount widget
custom_html = client.render_custom_amount(
  email: "donor@example.com",
  button_text: "Donate",
  placeholder: "Enter amount",
)

Rails

Setup

Create an initializer at config/initializers/sanwo.rb:

Rails.application.config.sanwo_client = Sanwo::Client.new(
  provider: "paystack",
  public_key: ENV.fetch("SANWO_PUBLIC_KEY"),
  currency: ENV.fetch("SANWO_CURRENCY", "NGN"),
  debug: Rails.env.development?,
)

The gem auto-registers a Sanwo::Rails::Helper in your views.

Add the script

Add the script tag to your layout, before </body>:

<%= sanwo_scripts %>

Checkout button

<%= sanwo_checkout(amount: 500_000, email: "customer@example.com", button_text: "Pay ₦5,000") %>

Available parameters

Parameter	Type	Required	Default	Description
amount	Integer	Yes	—	Amount in minor units (kobo, cents)
email	String	Yes	—	Customer email
button_text	String	No	"Pay Now"	Button label
button_class	String	No	"sanwo-button"	CSS class
description	String	No	—	Payment description
reference	String	No	Auto-generated	Transaction reference
currency	String	No	Config value	Currency code
first_name	String	No	—	Customer first name
last_name	String	No	—	Customer last name
phone	String	No	—	Customer phone
callback	String	No	—	JS callback function name

Custom amount form

<%= sanwo_custom_amount(email: "donor@example.com", button_text: "Donate", placeholder: "How much?") %>

Handling results

<script>
    function onPaid(result) {
        if (result.status === 'successful') {
            fetch('/payments/verify', {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                    'X-CSRF-Token': document.querySelector('meta[name="csrf-token"]').content
                },
                body: JSON.stringify({ reference: result.reference })
            });
        }
    }
</script>

<%= sanwo_checkout(amount: 500_000, email: "user@example.com", callback: "onPaid") %>

Providers

Sanwo::Providers::PAYSTACK
Sanwo::Providers::FLUTTERWAVE
Sanwo::Providers::RAZORPAY
Sanwo::Providers::MONNIFY
Sanwo::Providers::INTERSWITCH

Custom provider templates

client = Sanwo::Client.new(
  provider: "custom",
  public_key: "your_key",
  template_url: "https://example.com/my-provider-template.html",
  # or: template: '<div id="payment-form">...</div>',
)

For Rails, set it in the initializer:

Rails.application.config.sanwo_client = Sanwo::Client.new(
  provider: "custom",
  public_key: "your_key",
  template_url: "https://example.com/my-provider-template.html",
)

Source code

Sanwohq/ruby on GitHub.