Ibanity Elixir Library

The Ibanity Elixir Library provides convenient wrappers around the Ibanity API. The object attributes are dynamically defined based on the API response, supporting minor API changes seamlessly.

Documentation

Visit our API docs.

Installation

In the mix.exs file:

def deps do
  [{:ibanity, "~> 0.1.0}]
end

Configuration

The client supports multiple applications, that is multiple configurations. The reason for this is to enable, for example, sandbox or live environment, each having its own configurations options (certificate, private key, …).

There must be at least the :default application in your configuration file.

Signature

When making HTTP requests for live applications, each request must be signed, see API reference. Therefore the :signature_certificate_file, :signature_key_file and signature_certificate_id keys must be set. Please note that, at this time, Ibanity use the same certificate for both identifying and signing the requests, but it will change in a near future.

Required

Key	Description
`:certificate_file`	Path to the certificate used to identify your API client
`:key_file`	Path to the private key used to generate the identifying certificate. Note: the key should be in clear text
`:signature_certificate_file`	Path to the certificate used to sign HTTP requests to the API
`:signature_key_file`	Path to the private key used to generate the signing certificate. Note: the key should be in clear text
`:signature_certificate_id`	ID (UUIDv4) of the certificate used for signature

Optional

Key	Description
`:api_url`	Ibanity API endpoint. Default: `https://api.ibanity.com`
`:ssl_ca_file`	Path to the intermediate certificate file. Not needed in production environment

Example

The minimal configuration must be:

config :ibanity, :applications, [
  default: []
]

config :ibanity, :api_url, System.get_env("IBANITY_API_URL")

With that kind of configuration, requests won’t use SSL nor HTTP signature.

Here’s a full-fledged example with two applications, the :default one and :sandbox:

config :ibanity, :applications, [
  default: [
    certificate_file: System.get_env("DEFAULT_CERTIFICATE"),
    key_file: System.get_env("DEFAULT_KEY"),
    signature_certificate_file: System.get_env("DEFAULT_CERTIFICATE"),
    signature_certificate_id: System.get_env("DEFAULT_CERTIFICATE_ID"),
    signature_key_file: System.get_env("DEFAULT_KEY")
  ],
  sandbox: [
    certificate_file: System.get_env("SANDBOX_CERTIFICATE"),
    key_file: System.get_env("SANDBOX_KEY"),
    signature_certificate_file: System.get_env("SANDBOX_CERTIFICATE"),
    signature_certificate_id: System.get_env("SANDBOX_CERTIFICATE_ID"),
    signature_key_file: System.get_env("SANDBOX_KEY")
  ]
]

config :ibanity, :api_url, System.get_env("IBANITY_API_URL")
config :ibanity, :ssl_ca_file, System.get_env("IBANITY_CA_FILE")

Requirements

Elixir 1.6+.

Test

mix test

Usage

All operations take a Ibanity.Request structure as only parameter, though some convenience functions have been created in order to ease the use of the API.

For example, these:

FinancialInstitution.find("3851df38-b78a-447a-910e-5c077f30798b")

Request.id(:id, "3851df38-b78a-447a-910e-5c077f30798b")
|> FinancialInstitution.find

[id: "3851df38-b78a-447a-910e-5c077f30798b"]
|> Request.ids
|> FinancialInstitution.find

are strictly equivalent

A note on resource identifiers

In a RESTful API you sometimes have to provide multiple resource ids in the URL. In order to pass them to the request you should use Request.ids/2 to set them. This function takes a %Request{} as first parameter and a Keyword list as second one where the keys are the name of the ids as defined in the documentation - but in snake case - and the values are the matching UUIDs. See examples below.

Usage examples

Create a customer access token

[application_customer_reference: "12345"]
|> Request.attributes
|> Request.idempotency_key("007572ed-77a9-4828-844c-1fc0180b9795")
|> CustomerAccessToken.create

List financial institutions with paging options

Request.limit(1)
|> FinancialInstitutions.list

Update an existing financial institution using the :sandbox application

[name: "WowBank"]
|> Request.attributes
|> Request.idempotency_key("d49e91fb-58c4-4953-a4c3-71365139316d")
|> Request.ids(id: "0864492c-dbf4-43bd-8764-e0b52f4136d4")
|> Request.application(:sandbox)
|> FinancialInstitution.update

ibanity

v0.2.0