PaystackGateway

paystack-gateway is a Ruby library that provides easy-to-use bindings for the Paystack API. This library provides a collection of modules, methods and helpers for interacting with Paystack's API endpoints. It includes built-in error handling, caching, parsing, and logging.

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add paystack-gateway

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install paystack-gateway

Configuration

To use the PaystackGateway gem, you need to configure it with your Paystack secret key. You can do this in an initializer or directly in your application code.

The configuration options are

• secret_key: Your paystack api key used to authorize requests
• logger: Your ruby Logger. Default is Logger.new($stdout)
• logging_options: Options passed to Faraday logger middleware. Default is { headers: false }
• log_filter: Filter used when logging headers and body.

# config/initializers/paystack_gateway.rb

PaystackGateway.configure do |config|
  config.secret_key = Rails.application.credentials.dig(:paystack, :secret_key)
  config.logger = Rails.logger
  config.log_filter = lambda { |params|
    next params if !params || !params.respond_to?(:each)

    ActiveSupport::ParameterFilter.new(Rails.application.config.filter_parameters).filter(params)
  }
end

Usage

Calling API endpoints

Once configured, you can start using the various API modules and methods provided by the gem. They are designed to mirror how the api methods are grouped and listed on the Paystack API.

Here's an example creating a customer using the /customer/create endpoint.

response = PaystackGateway::Customers.create_customer(
  email: '[email protected]',
  first_name: 'Test',
  last_name: 'User',
)

response.id # => 203316808
response.customer_code # => "CUS_xsrozmbt8g1oear"

Error Handling

Whenever a network error occurs or the called endpoint responds with an error response, a PaystackGateway::ApiError(or a subclass of it) is raised that can be handled in your calling code.

Here's an example initializing a transaction using the /transaction/initialize endpoint

begin
  response = PaystackGateway::Transactions.initialize_transaction(
    email: '[email protected]',
    amount: 1000,
    reference: 'test_reference',
  )
  return response.payment_url

rescue InitializeTransactionError => e # subclass of PaystackGateway::ApiError
  cancel_payment if e.cancellable?

rescue PaystackGateway::ApiError => e
  handle_initialize_error(e)
end

Caching

While caching is implemented in the library, it is currently not configurable for all modules and api methods. With a little more work, this can be achieved. So if there's demand for it, I can work on it (PRs are also welcome 🙂).

Some endpoints currently make use of caching:

• Miscellaneous#list_banks
• Verifications#resolve_account_number

Caching works using an ActiveSupport::Cache::FileStore cache. The default caching period is 7 days and the cache data is stored on the file system at ENV['TMPDIR'] or /tmp/cache.

API Modules and Methods

Refer to the Paystack API documentation for details on all the available endpoints and their usage.

Implemented Modules and Methods

Below is a complete list of the API modules and methods that are currently implemented.

I invite you to collaborate on this project! If you need to use any of the unimplemented API methods or modules, or if you want to make modifications to the defaults or the level of configuration available in the currently implemented API methods, please feel free to raise a pull request (PR). See Contributing and Code of Conduct below

• Transactions

  • Initialize Transaction
  • Verify Transaction
  • List Transactions
  • Fetch Transaction
  • Charge Authorization
  • View Transaction Timeline
  • Transaction Totals
  • Export Transactions
  • Partial Debit

• Customers

  • Create Customer
  • List Customers
  • Fetch Customer
  • Update Customer
  • Validate Customer
  • Whitelist/Blacklist Customer
  • Deactivate Authorization

• Dedicated Virtual Accounts

  • Create Dedicated Virtual Account
  • Assign Dedicated Virtual Account
  • List Dedicated Accounts
  • Fetch Dedicated Account
  • Requery Dedicated Account
  • Deactivate Dedicated Account
  • Split Dedicated Account Transaction
  • Remove Split from Dedicated Account
  • Fetch Bank Providers

• Subaccounts

  • Create Subaccount
  • List Subaccounts
  • Fetch Subaccount
  • Update Subaccount

• Plans

  • Create Plan
  • List Plans
  • Fetch Plan
  • Update Plan

• Transfer Recipients

  • Create Transfer Recipient
  • Bulk Create Transfer Recipient
  • List Transfer Recipients
  • Fetch Transfer Recipient
  • Update Transfer Recipient
  • Delete Transfer Recipient

• Transfers

  • Initiate Transfer
  • Finalize Transfer
  • Initiate Bulk Transfer
  • List Transfers
  • Fetch Transfer
  • Verify Transfer

• Refunds

  • Create Refund
  • List Refunds
  • Fetch Refund

• Verification

  • Resolve Account Number
  • Validate Account
  • Resolve Card BIN

• Miscellaneous

  • List Banks
  • List/Search Countries
  • List States (AVS)

Development

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Make your changes, add tests for them.
4. Ensure the tests and linter pass
5. Open a pull request with a detailed description of your changes.

Setting up

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Running the tests and linter

Minitest is used for unit tests. Rubocop is used to enforce the ruby style.

To run the complete set of tests and linter run the following:

$ bundle install
$ bundle exec rake test
$ bundle exec rubocop

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/darthrighteous/paystack-gateway. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the PaystackGateway project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.