Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 79 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ The `paystack_sdk` gem provides a simple and intuitive interface for interacting
- [List Transactions](#list-transactions)
- [Fetch a Transaction](#fetch-a-transaction)
- [Get Transaction Totals](#get-transaction-totals)
- [Charges (Mobile Money)](#charges-mobile-money)
- [Customers](#customers)
- [Create a Customer](#create-a-customer)
- [List Customers](#list-customers)
Expand All @@ -30,6 +31,7 @@ The `paystack_sdk` gem provides a simple and intuitive interface for interacting
- [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)
Expand Down Expand Up @@ -200,6 +202,65 @@ else
end
```

### Charges (Mobile Money)

Initiate Mobile Money payments using the Charges API. This channel is available to businesses in Ghana, Kenya, and Côte d'Ivoire. See the Paystack guide: [Mobile Money](https://paystack.com/docs/payments/payment-channels/#mobile-money).

Supported providers (case-insensitive): `mtn`, `atl` (ATMoney/Airtel Money), `vod` (Vodafone), `mpesa`, `orange`, `wave`.

#### Create a Mobile Money Charge

```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", # e.g., GHS, KES, XOF
mobile_money: {
phone: "0551234987",
provider: "mtn" # mtn | atl | vod | mpesa | 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
```

#### Submit OTP (e.g., Vodafone voucher)

```ruby
otp_response = paystack.charges.submit_otp(
reference: "r13havfcdt7btcm",
otp: "123456"
)

puts otp_response.status # => "success" when authorized
```

#### Verify after timeout or via webhook

For offline flows, listen for `charge.success` webhooks. You may also verify after the provider timeout window. Note: `transactions.verify` expects a transaction reference (often the same `reference` you supplied when creating the charge once it converts to a transaction):

```ruby
verify = paystack.transactions.verify(reference: "r13havfcdt7btcm")
puts verify.status # "success", "failed", or current state
```

#### Verify a Transaction

```ruby
Expand Down Expand Up @@ -641,11 +702,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:
Expand Down