MercuryBanking

Client library for talking to Mercury API.

This gem comes in handy when you want to access all of your bank accounts and their transactions histories or make payments to existing recipients in your Mercury account.

Installation

Add this line to your application's Gemfile:

gem 'mercury_banking'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install mercury_banking

Usage

First initialize client:

require 'mercury_banking'

# For single account
client = Mercury::API.new("YOUR_API_KEY")

# For multiple accounts
multi_client = Mercury::Multi.new(['YOUR_API_KEY'])

Then call the API

client.accounts

multi_client.balances

CLI Usage

The gem also provides a command-line interface for interacting with Mercury Banking:

# Display all accounts
mercury accounts

# List transactions for an account
mercury transactions ACCOUNT_ID_OR_NUMBER

# Download all transactions as CSV files
mercury transactions_download

# Download transactions with custom options
mercury transactions_download --output_dir=my_transactions --start_date=2023-01-01 --end_date=2023-12-31

# Download transactions in beancount format
mercury transactions_download --format=beancount

# Download transactions in both CSV and beancount formats
mercury transactions_download --format=both

# Generate a balance sheet report
mercury financials balancesheet

# Generate a balance sheet report with custom options
mercury financials balancesheet --format=beancount --start=2023-01-01 --end=2023-12-31 --verbose

# Generate an income statement report
mercury financials incomestatement

The transactions_download command will download all Mercury transactions in the format:

transactions/YEAR-MO-Mercury-ACCOUNT-ID.csv

For example: transactions/2023-01-Mercury-123456789.csv

When using the --format=beancount option, it will create files in the format:

transactions/YEAR-MO-Mercury-ACCOUNT-ID.beancount

API Usage

For transferring money to a registered recipient:

client.transfer(
    recipient_id: RECIPIENT_ID,
    amount: 100000, # amount should be in USD
    account_id: ACCOUNT_ID,
    note: "TEST"
    )

json response:

{
    "amount": 1000000,
    "bankDescription": null,
    "counterpartyId": "dd486506-d66b-11e9-8d8a-0b2e6a550f30",
    "counterpartyName": "Fake P. Erson",
    "counterpartyNickname": null,
    "createdAt": "2019-09-13T21:17:15.974788Z",
    "dashboardLink": "https://mercury.com/transactions/dd4896c0-d66b-11e9-8d8a-cf31cc71dda0",
    "details": {
        "address": null,
        "domesticWireRoutingInfo": null,
        "electronicRoutingInfo": null,
        "internationalWireRoutingInfo": null
    },
    "estimatedDeliveryDate": "2019-09-13T21:17:17.387585Z",
    "failedAt": null,
    "id": "dd4896c0-d66b-11e9-8d8a-cf31cc71dda0",
    "kind": "externalTransfer",
    "note": null,
    "externalMemo": null,
    "postedAt": "2019-09-13T21:17:17.387585Z",
    "reasonForFailure": null,
    "status": "sent",
    "feeId": null
},

For transferring between two Mercury accounts:

multi_client.transfer(
    from: 'ACCOUNT_NAME_1',
    to: 'ACCOUNT_NAME_2',
    amount: 100000, # amount should be in USD
    note: 'test',
     email: '[email protected]',
     address: 'test address',
     city: 'Minato',
     region: 'Tokyo', # Either a two-letter US state code like "CA" for California or a free-form identification of a particular region worldwide
     postal_code: '1110000',
     country: 'JP' # ISO3166Alpha2 Ex. US, JP, etc.
     )

json_response:

{
    "amount": 1000000,
    "bankDescription": null,
    "counterpartyId": "dd486506-d66b-11e9-8d8a-0b2e6a550f30",
    "counterpartyName": "Fake P. Erson",
    "counterpartyNickname": null,
    "createdAt": "2019-09-13T21:17:15.974788Z",
    "dashboardLink": "https://mercury.com/transactions/dd4896c0-d66b-11e9-8d8a-cf31cc71dda0",
    "details": {
        "address": null,
        "domesticWireRoutingInfo": null,
        "electronicRoutingInfo": null,
        "internationalWireRoutingInfo": null
    },
    "estimatedDeliveryDate": "2019-09-13T21:17:17.387585Z",
    "failedAt": null,
    "id": "dd4896c0-d66b-11e9-8d8a-cf31cc71dda0",
    "kind": "externalTransfer",
    "note": null,
    "externalMemo": null,
    "postedAt": "2019-09-13T21:17:17.387585Z",
    "reasonForFailure": null,
    "status": "sent",
    "feeId": null
},

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests.

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.

Test

We use RSpec for testing. To run test use the following command:

rspec spec

or

rake spec

Testing

For running the test suite:

  1. Run bundle install
  2. Run bundle exec rspec to run the automated tests

For manual testing:

  1. Run bundle install
  2. Rename .env_test to .env
  3. Inside the .env file, add your Mercury API key
  4. Use the CLI commands to interact with the Mercury API

ToDo

  • To cover all endpoints
  • Throw useful errors
  • Encryption

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature).
  3. Commit your changes (git commit -am "Add new feature").
  4. Push to the branch (git push origin my-new-feature).
  5. Create a new Pull Request.

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

Release Notes

  • v1.0.0: Initial major release.

Reference

See Mercury docs for the complete list of endpoints.

License

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

Code of Conduct

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