Tikkie API

Unofficial Ruby library for communicating with the Tikkie API.

Installation

Add this line to your application's Gemfile:

gem 'tikkie-api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tikkie-api

Usage

Preparation

This library uses a JSON Web Token (JWT) as authentication method. You need to create a public/private key pair to sign the tokens. See the developer documentation from ABN AMRO to get started.

Make sure you have created an App in the developers portal with the Tikkie API product enabled. This App contains a Consumer Key (this is your API key), which you will need next.

Initialization

First create a Tikkie configuration and specify the API key of your App and the path to your private RSA key. Then use the configuration to initialize a Tikkie client:

require 'tikkie/api'

config = Tikkie::Api::Configuration.new("your_api_key", "private_rsa.pem")
client = Tikkie::Api::Client.new(config)

The configuration is created for the production environment by default. If you want to use the sandbox testing environment, then add the option test: true when creating the configuration:

config = Tikkie::Api::Configuration.new("your_api_key", "private_rsa.pem", test: true)

Platforms

Retrieve all platforms:

platforms = client.platforms.list

Create a new platform:

platform = client.platforms.create(
  name: "Kentaa",
  phone_number: "0601234567",
  platform_usage: Tikkie::Api::Types::PlatformUsage::FOR_MYSELF,
  email: "[email protected]",                      # optional
  notification_url: "https://kentaa.nl/tikkie"  # optional
)

platform_token = platform.platform_token

Users

Retrieve all users for a platform:

users = client.users.list("platform_token")

Create a new user for a platform:

user = client.users.create("platform_token",
  name: "Kentaa",
  phone_number: "0601234567",
  iban: "NL02ABNA0123456789",
  bank_account_label: "Personal account"
)

user_token = user.user_token
bank_account_token = user.bank_accounts.first.bank_account_token

Payment requests

Retrieve all payment requests for a user on a platform:

payment_requests = client.payment_requests.list("platform_token", "user_token")

The payments requests response is paginated. You can use the method more_elements? to determine if there's more data to retrieve. In the next request, set the offset parameter to the new offset using the method next_offset from the previous response. For example:

options = {}

loop do
  payment_requests = client.payment_requests.list("platform_token", "user_token", options)

  # Do something with payment requests

  break unless payment_requests.more_elements?

  options[:offset] = payment_requests.next_offset
end

To retrieve a single payment request:

payment_request = client.payment_requests.get("platform_token", "user_token", "payment_request_token")

Create a new payment request (i.e. Tikkie) for an existing user:

payment_request = client.payment_requests.create("platform_token", "user_token", "bank_account_token",
  amount: "5.00",               # optional
  currency: "EUR",
  description: "Test",
  external_id: "Invoice 12345"  # mandatory only when platform_usage is set to `FOR_MYSELF`
)

tikkie_url = payment_request.payment_request_url
payment_request_token = payment_request.payment_request_token

The parameter amount is optional. When omitted, it will create a payment request with an open amount, where the payer can decide on the amount.

Error handling

All responses to an API request include the methods success? and error? to determine whether the API call was successful or not. When the API request was not successful, the method errors will return details about the error response.

payment_request = client.payment_requests.create("platform_token", "user_token", "bank_account_token", ...)

if payment_request.success?
  # Success handling...

  redirect_to payment_request.payment_request_url
else
  # Error handling...

  puts payment_request.errors.inspect
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/KentaaNL/tikkie-api.

License

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