Paystack Ruby SDK

The official Ruby SDK for the Paystack API — generated from the Paystack OpenAPI specification.

---

Requirements

• Ruby 3.1 or later
• Standard library HTTP stack (net/http) — no extra runtime HTTP dependency

---

Installation

Add this to your application's Gemfile:

gem "paystack-ruby"

Then execute:

bundle install

Or install directly:

gem install paystack-ruby

---

Configuration

Paystack::Client takes your secret key as its only argument:

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

Use your Test Secret Key (sk_test_...) for development and Live Secret Key (sk_live_...) in production. Get them from your Paystack Dashboard.

---

Quick Start

Initialize a transaction and send the customer to authorization_url to pay:

require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

result = paystack.transaction.initialize(
  {
    email: "customer@example.com",
    amount: 100_000 # kobo
  }
)

puts result.data[:authorization_url]

Once the customer is redirected back, verify the transaction before you treat it as paid; never trust the redirect alone:

result = paystack.transaction.verify(reference)

if result.data[:status] == "success"
  # fulfil the order
end

---

Response Shape

All resource methods return a Paystack::Response object exposing:

response.http_status # Integer
response.status      # Boolean
response.message     # String
response.data        # Hash / Array / nil
response.meta        # Hash / nil

---

Error Handling

API failures raise a Paystack::Error, carrying the HTTP status and response body:

begin
  paystack.transaction.initialize({ email: "customer@example.com", amount: 100_000 })
rescue Paystack::Error => e
  puts e.message
  puts e.http_status
end

If you need to branch on failure type, rescue the specific subclass instead — Paystack::AuthenticationError, ValidationError, NotFoundError, RateLimitError, or ServerError:

begin
  paystack.transaction.initialize({ email: "customer@example.com", amount: 100_000 })
rescue Paystack::RateLimitError
  sleep(1)
  retry
end

---

API Reference

The SDK exposes one method per API resource on the Paystack::Client instance.

Resource	Property	Description	Methods
ApplePay	paystack.apple_pay	A collection of endpoints for managing application's top-level domain or subdomain accepting payment via Apple Pay	3
Balance	paystack.balance	A collection of endpoints gaining insights into the amount on an integration	2
Bank	paystack.bank	A collection of endpoints for managing bank details	3
BulkCharge	paystack.bulk_charge	A collection of endpoints for creating and managing multiple recurring payments	6
Charge	paystack.charge	A collection of endpoints for configuring and managing the payment channels when initiating a payment	7
Customer	paystack.customer	A collection of endpoints for creating and managing customers on an integration	12
DedicatedVirtualAccount	paystack.dedicated_virtual_account	A collection of endpoints for creating and managing payment accounts for customers	9
DirectDebit	paystack.direct_debit	A collection of endpoints for managing Direct Debit	2
Dispute	paystack.dispute	A collection of endpoints for managing transactions complaint made by customers	8
Integration	paystack.integration	A collection of endpoints for managing some settings on an integration	2
Miscellaneous	paystack.miscellaneous	A collection of endpoints that provides utility functions	3
Order	paystack.order	A collection of endpoints for creating and managing orders	5
Page	paystack.page	A collection of endpoints for creating and managing links for the collection of payment for products	6
PaymentRequest	paystack.payment_request	A collection of endpoints for managing invoices for the payment of goods and services	9
Plan	paystack.plan	A collection of endpoints for creating and managing recurring payment configuration	4
Product	paystack.product	A collection of endpoints for creating and managing inventories	5
Refund	paystack.refund	A collection of endpoints for creating and managing transaction reimbursement	4
Settlement	paystack.settlement	A collection of endpoints for gaining insights into payouts	2
Split	paystack.split	A collection of endpoints for spliting a transaction and managing the splits	6
Storefront	paystack.storefront	A collection of endpoints for creating and managing storefronts	11
Subaccount	paystack.subaccount	A collection of endpoints for creating and managing accounts for sharing a transaction with	4
Subscription	paystack.subscription	A collection of endpoints for creating and managing recurring payments	7
Terminal	paystack.terminal	A collection of endpoints for building delightful in-person payment experiences	8
Transaction	paystack.transaction	A collection of endpoints for managing payments	9
Transfer	paystack.transfer	A collection of endpoints for automating sending money to beneficiaries	11
TransferRecipient	paystack.transfer_recipient	A collection of endpoints for creating and managing beneficiaries that you send money to	6
VirtualTerminal	paystack.virtual_terminal	A collection of endpoints for building in-person payments without a physical terminal	9

Detailed method-level documentation for each resource is available in docs/.

---

Contributing

⚠️ This SDK is auto-generated from the Paystack OpenAPI specification. Regenerate instead of manually editing generated files.

To request endpoint/schema changes, open an issue or pull request against the Paystack OpenAPI specification.

---

License

MIT © Paystack