Elements Ruby SDK

Ruby bindings for the Elements API.

Installation

You may install the gem from Github Packages.

First, you must authenticate yourself to Github Packages by creating a personal access token. You may do that in Github Settings > Developer settings > Personal access tokens. Please follow the instructions here.

Then add the following to your Gemfile.

source 'https://rubygems.pkg.github.com/elementspay' do
  gem 'elements-pay', '>= 0.0.3'
end

Build the gem from source:

$ gem build elements-pay.gemspec

Configuration

This library requires you to configure the API key:

require "elements"

Elements.configure do |c|
  # You must set a valid api key
  c.api_key = "my_api_key"
  # Optionally, you can configure logging for request & response
  c.logger = Logger.new($stdout)
end

If you want to connect to the sandbox instead of production, you may configure the api_base to use the sandbox url:

require "elements"

Elements.configure do |c|
  c.api_base = Elements::ElementsConfiguration::SANDBOX_URL
end

Usage

require "elements"

# To create an authorized charge 
authorized_charge = Elements::Charge.create({
  amount: 30000,
  currency: "USD",
  payment_method_id: "PM-XXXXXX" 
})

# Access model attributes like object fields

authorized_charge.amount # 30000
authorized_charge.currency # "USD"
authorized_charge.captured? # false

# To capture the charge
captured_charge = Elements::Charge.capture(authorized_charge.id, 
                                           { amount: 30000 })

# To obtain a client token
client_token = Elements::ClientToken.create({ external_customer_id: "foo" })

# To retrieve payment method
payment_method = Elements::PaymentMethod.retrieve({
  payment_method_id: "PM-XXXXXX",
  external_customer_id: "foo" 
})

Please refer to our REST API docs for detailed API usage information.

Contribute

Begin by cloning the repository on GitHub.

$ git clone git@github.com:elementspay/elements-ruby-sdk.git
$ cd elements-ruby-sdk

You may then create your changes and issue pull requests.

Test your changes

It is encouraged to test your changes using RSpec and mocks, but if you want to perform some adhoc testing, you may do so with a REPL like IRB. You may also run ./bin/elements-console to launch the IRB session, this executable also includes Elements lib as a dependency for you automatically.

By default, the SDK connects to the production Elements API. You may test your changes with a local or a sandbox environment, by configuring the proper api_base and api_key:

require "elements"

Elements.configure do |c|
  c.api_base = "http://localhost:3000"
  c.api_key = "my local api key"
end

Release

First, bump the version number in lib/elements/version.rb, following the format of major.minor.patch

Then create a pull request and have the version bump merged into master.

After the master has been updated, check out a new tag according to the new version, say the new version is 1.6.7, then you should create a new tag called v1.6.7 and push that to remote.

Once the tag has been pushed, Github action will launch the .github/workflows/publish.yml, and you should watch for progress in https://github.com/elementspay/elements-ruby-sdk/actions.