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

Initialization

First create a Tikkie configuration and specify your API key and the path to your private RSA key. See also the developer documentation from ABN AMRO to get started.

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)

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:

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

while response.more_elements?
  response = client.payment_requests.list("platform_token", "user_token", offset: response.next_offset)
  payment_requests << response.to_a
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 for an existing user:

payment_request = client.payment_requests.create("platform_token", "user_token", "bank_account_token",
  amount: "5.00",
  currency: "EUR",
  description: "Test",
  external_id: "Invoice 12345"  # optional
)

tikkie_url = payment_request.payment_request_url
payment_request_token =payment_request.payment_request_token

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
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.