Increase

A Ruby API client for Increase, a platform for Bare-Metal Banking APIs!

Interact with Increase's API in a simple and Ruby-like manner.

Tip

I, @garyhtou, maintained the increase ruby gem up until June 15th, 2025. At which point, I passed the gem name ownership over to Increase since they shipped their own Ruby gem! You can find the official gem source code at Increase/increase-ruby.

The last release of this unofficial increase gem was v0.3.3.

🏦 Battle-tested at HCB

• Installation
• Usage
  • Per-request Configuration
  • Pagination
  • Error Handling
  • Configuration
  • File Uploads
  • Webhooks
  • Idempotency
• Development

Installation

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

$ bundle add increase -v 0.3.2

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

$ gem install increase -v 0.3.2

Usage

require'increase'# Grab your API key from https://dashboard.increase.com/developers/api_keysIncrease.api_key='my_api_key'Increase.base_url='https://api.increase.com'# List transactionsIncrease::Transactions.list# Retrieve a transactionIncrease::Transactions.retrieve('transaction_1234abcd')# Create an ACH TransferIncrease::AchTransfers.create(account_id: 'account_1234abcd',amount: 100_00,# 10,000 cents ($100 dollars)routing_number: '123456789',account_number: '9876543210',statement_descriptor: 'broke the bank for some retail therapy')

Per-request Configuration

By default, the client will use the global API key and configurations. However, you can define a custom client to be used for per-request configuration.

For example, you may want access to production and sandbox data at the same time.

sandbox=Increase::Client.new(api_key: 'playing_it_safe',base_url: 'https://sandbox.increase.com')# This request will use the `sandbox` client and its configurationsIncrease::Transactions.with_config(sandbox).list# => [{some sandbox transactions here}, {transaction}, {transaction}, ...]# This request will still use the global configurations (using production key)Increase::Transactions.list# => [{some production transactions here}, {transaction}, {transaction}, ...]

Alternatively, directly passing as hash to with_config works too!

Increase::Transactions.with_config(api_key: 'time_is_money',base_url: :sandbox).list# => [{some sandbox transactions here}, {transaction}, {transaction}, ...]

See the Configuration section for more information on the available configurations.

Pagination

When listing resources (e.g. transactions), Increase limits the number of results per page to 100. Luckily, the client will automatically paginate through all the results for you!

Increase::Transactions.list(limit: :all)do |transactions|
# This block will be called once for each page of resultsputs"I got #{transactions.count} transactions!"end# Or, if you'd like a gargantuan array of all the transactionsIncrease::Transactions.list(limit: :all)# You can also use the `next_cursor` to manually paginate through the resultstxns=Increase::Transactions.list(limit: 2_000,'created_at.after': '2022-01-15T06:34:23Z')# => [{transaction}, {transaction}, {transaction}, ...]txns.next_cursor# => "eyJwb2NpdGlvbiI6eyJvZmlzZXQiOjEwMH0sIm3pbHRlclI6e319"

Watch out for the rate limit!

Error Handling

Whenever you make an oopsie, the client will raise an error! Errors originating from the API will be a subclass of Increase::ApiError.

beginIncrease::Transactions.retrieve('i_dont_exist')rescueIncrease::ApiError=>eputse.message# "[404: object_not_found_error] Could not find the ..."putse.title# "Could not find the specified object."putse.detail# "No resource of type transaction was found with ID ..."putse.status# 404putse.response# This contains the full response, including headers!# => #<Faraday::Response:0x000000010b1fe2b0 ...>putse.class# Increase::ObjectNotFoundError (subclass of Increase::ApiError)end

To disable this behavior, set Increase.raise_api_errors = false. Errors will then be returned as a normal response.

Increase.raise_api_errors=false# Default: trueIncrease::Transactions.retrieve('i_dont_exist')# => {"status"=>404, "type"=>"object_not_found_error", ... }

Configuration

Name	Description	Default
api_key	Your Increase API Key. Grab it from https://dashboard.increase.com/developers/api_keys	nil
base_url	The base URL for Increase's API. You can use :production (https://api.increase.com), :sandbox (https://sandbox.increase.com), or set an actual URL	"https://api.increase.com"
raise_api_errors	Whether to raise an error when the API returns a non-2XX status. Learn more about Increase's errors here. See error classes here	true

There are multiple syntaxes for configuring the client. Choose your favorite!

# Set the configurations directlyIncrease.api_key='terabytes_of_cash'# Default: nil (you'll need one tho!)Increase.base_url=:production# Default: :productionIncrease.raise_api_errors=true# Default: true# Or, you can pass in a hashIncrease.configure(api_key: 'just_my_two_cents')# Or, you can use a block!Increase.configuredo |config|
config.api_key='digital_dough'config.base_url=:sandbox# Default: :productionconfig.raise_api_errors=false# Default: trueend

If you are using Rails, the recommended way is to set your configurations as a block in an initializer.

# config/initializers/increase.rbIncrease.configuredo |config|
# Your Increase API Key!# Grab it from https://dashboard.increase.com/developers/api_keysconfig.api_key=Rails.application.credentials.dig(:increase,:api_key)# The base URL for Increase's API.# You can use# - :production (https://api.increase.com)# - :sandbox (https://sandbox.increase.com)# - or set an actual URLconfig.base_url=Rails.env.production? ? :production : :sandbox# Whether to raise an error when the API returns a non-2XX status.# If disabled (false), the client will return the error response as a normal,# instead of raising an error.# # Learn more about...# - Increase's errors: https://increase.com/documentation/api#errors# - Error classes: https://github.com/garyhtou/increase-ruby/blob/main/lib/increase/errors.rbconfig.raise_api_errors=true# Default: trueend

File Uploads

It's as simple as passing in a file path!

Increase::Files.create(purpose: 'identity_document',file: '/path/to/file.jpg')

Alternatively, you can pass in a File object.

file=File.open('/path/to/file.jpg')Increase::Files.create(purpose: 'identity_document',file: file)

Or, get even fancier and use Increase::FileUpload to specify the content type and filename.

file=Increase::FileUpload.new('/path/to/file.jpg',content_type: 'image/jpeg',filename: 'my_file.jpg')Increase::Files.create(purpose: 'identity_document',file: file)

If no content type or filename is provided, the client will try to guess it.

Webhooks

Increase's webhooks include a Increase-Webhook-Signature header for securing your webhook endpoint. Although not required, it's strongly recommended that you verify the signature to ensure the request is coming from Increase.

Here is an example for Rails.

classIncreaseController < ApplicationControllerprotect_from_forgeryexcept: :webhook# Ignore CSRF checksdefwebhookpayload=request.body.readsig_header=request.headers['Increase-Webhook-Signature']secret=Rails.application.credentials.dig(:increase,:webhook_secret)Increase::Webhook::Signature.verify(payload: payload,signature_header: sig_header,secret: secret)# It's a valid webhook! Do something with it...renderjson: {success: true}rescueIncrease::WebhookSignatureVerificationError=>erenderjson: {error: 'Webhook signature verification failed'},status: :bad_requestendend

Idempotency

Increase supports idempotent requests to allow for safely retrying requests without accidentally performing the same operation twice.

card=Increase::Cards.create({# Card parametersaccount_id: 'account_1234abcd',description: 'My Chipotle card'},{# Request headers'Idempotency-Key': 'use a V4 UUID here'})# => {"id"=>"card_1234abcd", "type"=>"card", ... }card.idempotent_replayed# => nil# Repeat the exact same requestcard=Increase::Cards.create(...)# => {"id"=>"card_1234abcd", "type"=>"card", ... }card.idempotent_replayed# => "true"

Reusing the key in subsequent requests will return the same response code and body as the original request along with an additional HTTP header (Idempotent-Replayed: true). This applies to both success and error responses. In situations where your request results in a validation error, you'll need to update your request and retry with a new idempotency key.

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.

You can also run INCREASE_API_KEY=my_key_here INCREASE_BASE_URL=https://sandbox.increase.com bin/console to run the console with your Increase sandbox API key pre-filled.

To install this gem onto your local machine, run bundle exec rake install.

To release a new version:

• gem bump --version patch|minor|major
  • Make sure you have gem-release installed
• Update the CHANGELOG and README if necessary
• bundle exec rake release
• Create release on GitHub from newly created tag

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/garyhtou/increase.

License

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

---

Please note that this is not an official library by Increase. This gem was created and maintained by Gary Tou.