OmiseGO

OmiseGO is a Ruby SDK meant to communicate with an OmiseGO eWallet setup.

Installation

Add this line to your application's Gemfile:

gem 'omisego'

And then execute:

$ bundle

Or install it yourself as:

$ gem install omisego

Initialization

The OmiseGO SDK can either be initialized on a global level, or a on client basis. However, initializing on a global level is not necessarily what you want and won't be thread-safe. If using Rails, Sticking a client method in your ApplicationController will probably be a better solution than using an initializer as shown below.

In the end, the choice is yours and the optimal solution depends on your needs.

Global init

# config/initializers/omisego.rb
OmiseGO.configure do |config|
  config.access_key = ENV['OMISEGO_ACCESS_KEY']
  config.secret_key = ENV['OMISEGO_SECRET_KEY']
  config.base_url   = ENV['OMISEGO_BASE_URL']
end

If initialized this way, the OmiseGO classes can be used without specifying the client.

user = OmiseGO::User.find(provider_user_id: 'some_uuid')

Logging

The Ruby SDK comes with the possibility to log requests to the eWallet. For example, within a Rails application, the following can be defined:

# config/initializers/omisego.rb
OmiseGO.configure do |config|
  config.access_key = ENV['OMISEGO_ACCESS_KEY']
  config.secret_key = ENV['OMISEGO_SECRET_KEY']
  config.base_url   = ENV['OMISEGO_BASE_URL']
  config.logger     = Rails.logger
end

This would provide the following in the logs:

[OmiseGO] Request: POST login
User-Agent: Faraday v0.13.1
Authorization: [FILTERED]
Accept: application/vnd.omisego.v1+json
Content-Type: application/vnd.omisego.v1+json

{"provider_user_id":"aeab0d51-b3d9-415d-98ef-f9162903f024"}

[OmiseGO] Response: HTTP/200
Connection: close
Server: Cowboy
Date: Wed, 14 Feb 2018 04:35:52 GMT
Content-Length: 140
Content-Type: application/vnd.omisego.v1+json; charset=utf-8
Cache-Control: max-age=0, private, must-revalidate

{"version":"1","success":true,"data":{"object":"authentication_token","authentication_token":[FILTERED]}}

Client init

With this approach, the client needs to be passed in every call and will be used as the call initiator.

client = OmiseGO::Client.new(
  access_key: ENV['OMISEGO_ACCESS_KEY'],
  secret_key: ENV['OMISEGO_SECRET_KEY'],
  base_url:   ENV['OMISEGO_BASE_URL']
)

user = OmiseGO::User.find(provider_user_id: 'some_uuid', client: client)

Usage

All the calls below will communicate with the OmiseGO wallet specified in the base_url configuration. They will either return an instance of OmiseGO:Error or of the appropriate model (User, Balance, etc.), see the list of models for more information.

The method #error? can be used on any model to check if it's an error or a valid result.

Managing Users

Find

Retrieve a user from the eWallet API.

user = OmiseGO::User.find(
  provider_user_id: 'some_uuid'
)

Returns either:

  • An OmiseGO::User instance
  • An OmiseGO::Error instance

Create

Create a user in the eWallet API database. The provider_user_id is how a user is identified and cannot be changed later on.

user = OmiseGO::User.create(
  provider_user_id: 'some_uuid',
  username: '[email protected]',
  metadata: {
    first_name: 'John',
    last_name: 'Doe'
  }
)

Returns either:

  • An OmiseGO::User instance
  • An OmiseGO::Error instance

Update

Update a user in the eWallet API database. All fields need to be provided and the values in the eWallet database will be replaced with the sent ones (behaves like a HTTP PUT). Sending metadata: {} in the request below would remove the first_name and last_name fields for example.

user = OmiseGO::User.update(
  provider_user_id: 'some_uuid',
  username: '[email protected]',
  metadata: {
    first_name: 'Jane',
    last_name: 'Doe'
  }
)

Returns either:

  • An OmiseGO::User instance
  • An OmiseGO::Error instance

Managing Sessions

Login

Login a user and retrieve an authentication_token that can be passed to a mobile client to make calls to the eWallet API directly.

auth_token = OmiseGO::User.(
  provider_user_id: 'some_uuid'
)

Returns either:

  • An OmiseGO::AuthenticationToken instance
  • An OmiseGO::Error instance

Managing Balances

All

Retrieve a list of addresses (with only one address for now) containing a list of balances.

address = OmiseGO::Balance.all(
  provider_user_id: 'some_uuid'
)

Returns either:

  • An OmiseGO::Address instance
  • An OmiseGO::Error instance

Credit

Transfer the specified amount (as an integer, down to the subunit_to_unit) from the master wallet to the specified user's wallet. In the following methods, an idempotency token is used to ensure that one specific credit/debit occurs only once. The implementer is responsible for ensuring that those idempotency tokens are unique - sending the same one two times will prevent the second transaction from happening.

address = OmiseGO::Balance.credit(
  provider_user_id: 'some_uuid',
  token_id: 'OMG:5e9c0be5-15d1-4463-9ec2-02bc8ded7120',
  amount: 10_000,
  idempotency_token: "123",
  metadata: {}
)

To use the primary balance of a specific account instead of the master account's as the sending balance, specify an account_id:

address = OmiseGO::Balance.credit(
  account_id: 'account_uuid',
  provider_user_id: 'some_uuid',
  token_id: 'OMG:5e9c0be5-15d1-4463-9ec2-02bc8ded7120',
  amount: 10_000,
  idempotency_token: "123",
  metadata: {}
)

Debit

Transfer the specified amount (as an integer, down to the subunit_to_unit) from the specified user's wallet back to the master wallet.

address = OmiseGO::Balance.debit(
  provider_user_id: 'some_uuid',
  token_id: 'OMG:5e9c0be5-15d1-4463-9ec2-02bc8ded7120',
  amount: 10_000,
  idempotency_token: "123",
  metadata: {}
)

To use the primary balance of a specific account instead of the master account as the receiving balance, specify an account_id:

address = OmiseGO::Balance.debit(
  account_id: 'account_uuid',
  provider_user_id: 'some_uuid',
  token_id: 'OMG:5e9c0be5-15d1-4463-9ec2-02bc8ded7120',
  amount: 10_000,
  idempotency_token: "123",
  metadata: {}
)

By default, points won't be burned and will be returned to the account's primary balance (either the master's balance or the account's specified with account_id). If you wish to burn points, send them to a burn address. By default, a burn address identified by 'burn' is created for each account which can be set in the burn_balance_identifier field:

address = OmiseGO::Balance.debit(
  account_id: 'account_uuid',
  burn_balance_identifier: 'burn',
  provider_user_id: 'some_uuid',
  token_id: 'OMG:5e9c0be5-15d1-4463-9ec2-02bc8ded7120',
  amount: 10_000,
  idempotency_token: "123",
  metadata: {}
)

Getting settings

All

Retrieve the settings from the eWallet API.

settings = OmiseGO::Setting.all

Returns either:

  • An OmiseGO::Setting instance
  • An OmiseGO::Error instance

Listing transactions

Params

Some parameters can be given to the two following methods to customize the returned results. With them, the list of results can be paginated, sorted and searched.

  • page: The page you wish to receive.
  • per_page: The number of results per page.
  • sort_by: The sorting field. Available values: id, status, from, to, created_at, updated_at
  • sort_dir: The sorting direction. Available values: asc, desc
  • search_term: A term to search for in ALL of the searchable fields. Conflict with search_terms, only use one of them. See list of searchable fields below (same as search_terms).
  • search_terms: A hash of fields to search in:
{
  search_terms: {
    from: "address_1"
  }
}

Available values: id, idempotency_token, status, from, to

All

Get the list of transactions from the eWallet API.

transaction = OmiseGO::Transaction.all

Returns either:

  • An OmiseGO::List instance of OmiseGO::Transaction instances
  • An OmiseGO::Error instance

Parameters can be specified in the following way:

transaction = OmiseGO::Transaction.all(params: {
  page: 1,
  per_page: 10,
  sort_by: 'created_at',
  sort_dir: 'desc',
  search_terms: {
    from: "address_1",
    to: "address_2",
    status: "confirmed"
  }
})

All for user

Get the list of transactions for a specific provider user ID from the eWallet API.

transaction = OmiseGO::Transaction.all_for_user(
  provider_user_id: "some_uuid"
)

Returns either:

  • An OmiseGO::List instance of OmiseGO::Transaction instances
  • An OmiseGO::Error instance

Parameters can be specified in the following way:

transaction = OmiseGO::Transaction.all(params: {
  page: 1,
  per_page: 10,
  sort_by: 'created_at',
  sort_dir: 'desc',
  search_terms: {
    from: "address_1",
    status: "confirmed"
  }
})

Since those transactions are already scoped down to the given user, it is NOT POSSIBLE to specify both from AND to in the search_terms. Doing so will result in the API ignoring both of those fields for the search.

Models

Here is the list of all the models available in the SDK with their attributes.

OmiseGO::Address

Attributes:

  • address (string)
  • balances (array of OmiseGO::Balance)

OmiseGO::Balance

Attributes:

  • amount (integer)
  • minted_token (OmiseGO::MintedToken)

OmiseGO::AuthenticationToken

Attributes:

  • authentication_token (string)

OmiseGO::Pagination

Attributes

  • per_page (integer)
  • current_page (integer)
  • first_page? (boolean)
  • last_page? (boolean)

OmiseGO::List

Attributes:

  • data (array of models)
  • pagination (OmiseGO::Pagination)

OmiseGO::MintedToken

Attributes:

  • symbol (string)
  • name (string)
  • subunit_to_unit (integer)

OmiseGO::User

Attributes:

  • id (string)
  • username (string)
  • provider_user_id (string)
  • metadata (hash)

OmiseGO::Exchange

  • rate (integer)

OmiseGO::TransactionSource

  • address (string)
  • amount (integer)
  • minted_token (OmiseGO::MintedToken)

OmiseGO::Transaction

  • id (string)
  • idempotency_token (string)
  • amount (integer)
  • minted_token (OmiseGO::MintedToken)
  • from (OmiseGO::TransactionSource)
  • to (OmiseGO::TransactionSource)
  • exchange (OmiseGO::Exchange)
  • status (string)
  • created_at (string)
  • updated_at (string)

OmiseGO::Error

Attributes:

  • code (string)
  • description (string)
  • messages (hash)

Live Tests

Live tests are recorded using VCR. However, they have been updated to hide any access/secret key which means deleting them and re-running the live tests will fail. It is first required to update the spec/env.rb file with real keys. Once the VCR records have been re-generated, do not forget to replace the Authorization header in all of them using the base64 encoding of fake access and secret keys.

Development

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

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

License

The OmiseGO Ruby SDK is released under the Apache License.