Monzo

A simple interface to make requests to the Monzo API. Full API documentation can be found at https://monzo.com/docs/.

Before using this gem please ensure you read Monzo's update on their API ensuring you understand Monzo's development plans and are happy that they are likely to introduce backwards-incompatible changes to the API when developing the new Current Account functionality.

Installation

Add this line to your application's Gemfile:

gem "monzo"

And then execute:

$ bundle

Or install it yourself as:

$ gem install monzo

Usage

Introduction

The Monzo API implements OAuth 2.0 to allow users to log in to applications without exposing their credentials. The process involves several steps:

1. Acquire an access token, and optionally a refresh token
2. Use the access token to make authenticated requests
3. If you were issued a refresh token: refresh the access token when it expires

Before you begin, you will need to create a client in the developer tools. To understand how to acquire an access token see the Monzo API documentation

Once you have acquired an access token you can configure the gem to use it. Firstly require the gem:

require "monzo"

Then configure your access token:

Monzo.configure("access_token")

After you have set your access token you can now make requests.

Accounts

Accounts represent a store of funds, and have a list of transactions. Docs

# Find all Monzo Accounts
Monzo::Account.all

Pots

A Pot is a place to keep some money separate from your main spending account. Docs

# Find all Monzo Pots
Monzo::Pot.all

# Find a pot with the given pot id.
Monzo::Pot.find(pot_id)

# Move money into a pot
account_id = Monzo::Account.all.last.id # The account to withdraw from
pot = Monzo::Pot.all.first # Get the first pot
pot.balance #=> eg. 5000

pot.deposit!(100, account_id)
pot.balance  #=> eg. 5100

# Move money out of a pot
account_id = Monzo::Account.all.last.id
pot = Monzo::Pot.all.first
pot.balance #=> eg. 5000

pot.withdraw!(100, account_id)
pot.balance  #=> eg. 4900

The deposit! and withdrawl! methods accept an optional dedupe_id parameter. It's used to prevent duplicate transactions and should remain static between retries to ensure only one deposit/withdrawl is created. If you don't provide one, a random string will be generated for each deposit/withdrawl. You should always provide this if there is a chance the transaction will be retried.

dedupe_id = 'SomeniqueDeDuplicationString' # Store this and use it for retries.
pot.deposit!(100, account_id, dedupe_id)

Balance

Retrieve information about an account’s balance. Docs

# Find the balance of the given account id
Monzo::Balance.find(account_id)

Transactions

Transactions are movements of funds into or out of an account. Negative transactions represent debits (ie. spending money) and positive transactions represent credits (ie. receiving money). Docs

# Find a transaction with the given transaction id.
Monzo::Transaction.find(transaction_id)

# Find all the transactions for a given account id.
Monzo::Transaction.all(account_id)

# Create an annotation for a given transaction id.
metadata = { :foo => "bar" }
Monzo::Transaction.create_annotation(transaction_id, metadata)

Feed Items

The Monzo app is organised around the feed – a reverse-chronological stream of events. Transactions are one such feed item, and your application can create its own feed items to surface relevant information to the user. Docs

# Create a feed item on a user's feed.
feed_item_type = "basic"
feed_item_params = {
  :title => "Hello World",
  :image_url => "https://www.example.com/image.png"
}
url = "https://www.example.com"
Monzo::FeedItem.create(account_id, feed_item_type, feed_item_params, url)

Webhooks

Webhooks allow your application to receive real-time, push notification of events in an account. Docs

# Create a webhook for the given account id.
Monzo::Webhook.create(account_id, "https://example.com")

# Find all webhooks for a given account id.
Monzo::Webhook.all(account_id)

# Delete a webhook.
Monzo::Webhook.delete(webhook_id)

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.

Contributing

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

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

License

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