Bunq::Client

The Bunq::Client is a ruby wrapper of the bunq Public API extracted from Jortt Online boekhouden.

The Bunq::Client is the main interface which can be used to navigate to other resources. The response objects are just hashes similar to the documentation of the bunq API. Only the content of Response is returned.

The bunq Pagination is implemented using a ruby Enumerator. All index methods are Paginated. This means you can loop through large resultsets without loading everything into memory.

Installation

Add this line to your application's Gemfile:

gem 'bunq-client'

And then execute:

$ bundle

Or install it yourself as:

$ gem install bunq-client

One time setup

1. Create installation

# Generate keys on the fly. Make sure you save these keys in a secure location.
# Alternatively use keys already generated.
openssl_key = OpenSSL::PKey::RSA.new(2048)
public_key = openssl_key.public_key.to_pem
private_key = openssl_key.to_pem

Bunq.configure do |config|
  config.api_key = 'YOUR API KEY'
  config.private_key = private_key
  config.server_public_key = nil # you don't have this yet
  config.installation_token = nil # this MUST be nil for creating installations
end

# Create the installation
installation = Bunq.client.installations.create(public_key)

# Print the installation token to put in your Bunq::Configuration
installation_token = installation[1]['Token']['token']
puts "config.installation_token = #{installation_token}"

# Keep the public key to put in your Bunq::Configuration
server_public_key_location = "./server_public_key.pub"
File.open(server_public_key_location, 'w') { |file| file.write(installation[2]['ServerPublicKey']['server_public_key']) }
puts "config.server_public_key written to file #{server_public_key_location}"

2. Register your device as device server This is typically your application server (or your laptop when playing around).

Bunq.configure do |config|
  config.api_key = 'YOUR API KEY'
  # Used for request signing
  config.private_key = 'SAME PRIVATE KEY AS IN STEP 1'
  # Used for response verification
  config.server_public_key = 'THE CONTENTS OF THE PUBLIC KEY FILE RETURNED IN STEP 1'
  config.installation_token = 'THE INSTALLATION TOKEN RETURNED IN STEP 1'
end

response = Bunq.client.device_servers.create('My Laptop')
puts "Device server created: #{response[0]['Id']['id']}"

3. Optional: Pin certificate (if you want to receive callbacks)

Bunq.configure do |config|
  config.api_key = 'YOUR API KEY'
  # Used for request signing
  config.private_key = 'SAME PRIVATE KEY AS IN STEP 1'
  # Used for response verification
  config.server_public_key = 'THE CONTENTS OF THE PUBLIC KEY FILE RETURNED IN STEP 1'
  config.installation_token = 'THE INSTALLATION TOKEN RETURNED IN STEP 1'
end

certificate_of_you_callback_url = IO.read('path_to_pem_file')
Bunq.client.me_as_user.certificate_pinned.create(certificate_of_you_callback_url)

4. Optional: Register callback url (for realtime updates of e.g. payments)

Bunq.configure do |config|
  config.api_key = 'YOUR API KEY'
  # Used for request signing
  config.private_key = 'SAME PRIVATE KEY AS IN STEP 1'
  # Used for response verification
  config.server_public_key = 'THE CONTENTS OF THE PUBLIC KEY FILE RETURNED IN STEP 1'
  config.installation_token = 'THE INSTALLATION TOKEN RETURNED IN STEP 1'
end

Bunq.client.me_as_user.notification_filter_url.create(
  [{
    "notification_target": 'https://YOUR_CALLBACK_URL',
    "category": "PAYMENT"
  }]
)

Usage

Bunq.configure do |config|
  
  # Mandatory configuration after inital setup phase
  config.api_key = 'YOUR API KEY' 
  # Private key used for request signing
  config.private_key = 'YOUR PRIVATE KEY'
  # Public key from bunq retrieved via Bunq.client.installations.create
  config.server_public_key = 'SERVER PUBLIC KEY'
  # Installation token retrieved via Bunq.client.installations.create
  config.installation_token = 'YOUR INSTALLATION TOKEN'

  
  # Optional configuration for access to the sandbox
  # config.sandbox = true 
  # if config.sandbox
  #  config.sandbox_user = 'USER'
  #  config.sandbox_password = 'PASSWORD'
  # end
end

# List id's of all your monetary_accounts
Bunq.client.me_as_user.monetary_accounts.index.each do |monetary_account|
  puts monetary_account['MonetaryAccountBank']['id']
end

Session caching

By default, each Bunq.client creates a new session. If you want to share a session between multiple Bunq.clients, use the following configuration:

Bunq.configure do |config|
  config.session_cache = Bunq::ThreadSafeSessionCache.new
end

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.

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.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/jorttbv/bunq-client. 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.

License

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