Concepts
Authentication
Access to the Imburse API is granted using JWT bearer tokens. A bearer token is generated by sending an HMAC signed request to our Authentication API using the public and private keys generated for your account and/or tenant.
API Keys
An API Key is a Public and Private key set and is used as a means of securing your request during the authentication process. The API Key has one or more roles attributed to it and these roles govern the API Keys’ API access.
Account API Keys can manage accounts and create and manage the Tenant API Keys. Tenant API Keys can manage everything for the Tenant. ie, Apps, Schemes, etc.
A Tenant API key can have multiple roles assigned depending on its purpose.
You can fully control the creation of Tenant API Keys along with the permissions that they have. For example, if you want to generate just one Tenant API Key with the ability to create other Tenant API Keys, select the tenant-admin role. In this case, the Tenant is independent of the Account holder and able to self-provision within its area.
Alternatively, you can create a Tenant API key with limited functionality, such as restrictions from creating their own keys.
See below the available roles:
| Role | Description |
|---|---|
tenant-admin | Read and write access to all aspects of a Tenant, including Users and API Keys. |
tenant-management | Tenant information access. |
tenant-app-read | Apps read access. |
tenant-app-write | Apps read and write access. |
tenant-collect-scheme-read | Collect Schemes read access. |
tenant-collect-scheme-write | Collect Schemes read and write access. |
tenant-payout-scheme-read | Payout Schemes read access. |
tenant-payout-scheme-write | Payout Schemes read and write access. |
tenant-reward-group-read | Reward Groups read access. |
tenant-reward-group-write | Reward Groups write access. |
tenant-transaction-read | Transactions read access. |
tenant-transaction-write | Transactions read and write access. |
HMAC
HMAC stands for Hash-based message authorization code and is a stronger type of authentication, more common in financial APIs.
With HMAC, both the sender and receiver know a secret key that no one else does. The client creates a unique HMAC, or hash, per request to the server by hashing the request data with the private keys and sending it as part of a request.
What makes HMAC more secure than Message Authentication Code (MAC) is that the key and the message are hashed in separate steps.
HMAC(key, msg) = H(mod1(key) || H(mod2(key) || msg))This type of authorization ensures the process is not susceptible to extension attacks that add to the message and can cause elements of the key to be leaked as successive MACs are created.
When the server receives the request and regenerates its own unique HMAC, it compares the two HMACs.
If they are equal, the client is defined as trusted and the request is executed.
This process is often called a secret handshake.
More information on HMAC signature creation, with examples on how to generate one, can be found on github here.Access Token
Once authenticated via the HMAC authentication scheme, Imburse will return a Bearer token, that is needed for the authorization in subsequent requests.
The HMAC scheme is extremely secure but is computationally quite expensive, both on the client and the server; hence why Imburse returns a Bearer token once authenticated.
The Bearer token returned as the access token, is a cryptic string signed on the Imburse platform and validated on the server for each API request.
Imburse Portals
Account
Having signed up to the Imburse Platform, you will have been provided with a set up Account. This account represents your organization from a license management and billing perspective.
It also acts as the administrative root of your Imburse Platform, holding one or more Tenants. You can access and manage your account either through its portal, a user-friendly web hosted user interface, or using its REST API directly.
To be able to login, once setup the Account, it is also necessary to create and add a User (or as many you wish to have) in order so these users can log into the portal. If you do not have access to your account, please reach out to your Account Manager.
Login into the portal, you can find on the left the tab to create new users, below Tenants – Users.
Tenant
The tenant level gives you access to the Imburse Platform’s functionality. You can consider a Tenant as either a company, department, broker or organization and can add as many Tenants to your Account as agreed commercially.
The Tenant serves three main purposes:
- Configuration and management for marketplace apps, schemes, and reporting
- execution of instructions
- logical isolation a segregation of data and processing within a multi-tenancy system as tenants do not share information with each other
The configuration of the Tenant can be managed through the Tenant Portal, or using its REST API directly.
Environments
Imburse provides its users with two environments: Sandbox and Production. The following table provides a description of these environment types along with the appropriate URLs:
| Environment | Description | REST API: | Account Portal | Tenant Portal |
|---|---|---|---|---|
| Sandbox | Your place to integrate, experiment and test to get a production-like experience. | https://sandbox-api.imbursepayments.com | https://sandbox-account.imbursepayments.com | https://sandbox-portal.imbursepayments.com |
| Production | Once you are ready, your place to see, experience, and interact with the latest version of Imburse product. | https://api.imbursepayments.com | https://account.imbursepayments.com | https://portal.imbursepayments.com |
Marketplace
At the Imburse Marketplace is where you can find access to already connected Providers and Partners. This is where you can find a variety of payment service providers, banks and others, to install on your Tenant and start using instantly.
Apps
Imburse connects to providers and their services by way of Apps. You install and configure one or more Apps so that Imburse can connect and push your payment requests through them.
To configure your desired App, an agreement with the referent PSP or Financial Institutions will be needed, so valid PSP credentials to use the App can be obtained.
Rewards
Imburse offers Rewards as a payout solution, allowing your business to offer its customers the option to receive the owed funds in form of a reward such a voucher from their favourite brand.
Scheme
Schemes define a set of rules by which an Imburse client can:
- collect payments
- issue payouts
- track financial instruments, for example, movements on bank accounts
They can be thought of as workflows: they determine the available payment methods to present to a customer, the partner through which to route a specific transaction, the possible rewards the customer may claim, or help map an incoming transaction event to the appropriate outgoing notifications.
The Scheme allows Imburse platform to know how to route payment instructions to the appropriate partner. Schemes work as follows: 1. You define a scheme with a set of rules where each rule can have one or more associated Apps. 2. Payment instructions for that scheme have their attributes compared to each rule. 3. The matched rule determines the App(s) available to process that instruction. 4. The financial instrument (e.g. a Mobile phone number, Card Number) is then used to determine the payment method and App combination to use for processing the payment
A Scheme consists of three main components, where each component contains one or more instances of the following one:
- Drafts
- Rules
- Apps
Drafts
The Drafts component allows for multiple draft scheme versions to be added. Only one draft scheme will be published at any one time. This frees you to work on setting a new scheme and save it before you publish it. A scenario where this would be useful is if you have a scheme that is currently live, and you want to make a change to it. You can create a new draft scheme, configure it exactly how you want, and then publish it sometime in the future - maybe at an off-peak time or during a weekend for example.
| Action | Description |
|---|---|
| Adding Drafts | You can add as many drafts in your scheme as required. |
| Publishing a Draft | Publishing a draft scheme will make the draft scheme live for the scheme. If the scheme is being used in your live platform, the effect is that the new rules and apps etc. will apply immediately to the next collection that occurs for the scheme. |
| Updating Drafts | You can add update any draft except the published Draft. If you need to update the published draft, you should add a new draft that is a mirror of the published draft and then publish the new draft. |
| Deleting Drafts | You can add delete any Draft except the published draft. |
Rules
The rules within a draft scheme allow you to explicitly control the options available in your scheme. A Rule defines filters for currencies, countries, and a value range, and then explicitly defines which App to use when this Rule is matched. You can add as many Rules to your draft scheme as necessary to refine the available collection options to meet your requirements.
Apps
Given a particular rule, one must assign an App. The App determines the available payment method(s) and partner integration(s) to use for the scheme and rule. A single rule cannot have more than a single App exposing a specific payment method. That is because the partner choice is transparent to the end customer, they are just allowed to choose how to pay or be paid.
Orders and Instructions
Orders and Instructions are representations of an intention to collect or payout an amount and hold the necessary details to allow Imburse to process a collection or payout on your behalf.
An Order is a wrapper for multiple instructions, and it is used for logically grouping of payments, e.g., an Order can be a policy, or a subscription. The instruction within an order is what is the intent to collect, or payout and it is what will become the transaction processed by chosen App.
To DEBIT (collect) or CREDIT (payout) your customers, these two elements will need to be created.
Order
The Order consists of the following attributes:
| Field | Description |
|---|---|
| OrderRef | This is a unique reference for an order, such as a policy number, invoice number etc. It should not be made up of personal identifiable information. |
| CustomerDefaults | When an Order has multiple instructions, it is more convenient to set a default payment instrument and scheme for all instructions in the order, instead of setting it against each instruction. A scenario for this would be when you have a 12-month subscription and want to use the same credit card token for all 12 monthly instructions in the order. In this case, if the credit card expires, you only have to update the default financial instrument to a new token instead of individually changing each instruction. |
| Metadata | This is a key/value dictionary for which you can add any relevant information you want for your own reporting purposes, e.g: a policy Id/number, broker name/Id, billing reference, etc. |
| Instructions | An array of all the instructions for this Order. |
Instruction
An Instruction consists of the following attributes:
| Field | Description |
|---|---|
| InstructionRef | This is a unique reference for an instruction. It should not contain any personal identifiable information. |
| CustomerRef | This is a unique customer reference. It should not contain any personal identifiable information. |
| Metadata | This is a key/value dictionary to which you can add any relevant information you might need (e.g., for your own reporting purposes). |
| Direction | This is used to signal whether the instruction represents a CREDIT (payout) or a DEBIT (collection). |
| FinancialInstrumentId | The id of the financial instrument to use for this instruction. |
| Amount | The amount for the transaction. |
| Currency | The currency the transaction will use. |
| Country | The country that the transaction applies to. |
| SettleByDate | The date when the transaction should be settled. If the transaction should be executed immediately, then this value must be set to the current date. |
| SchemeId | The Id of the scheme that was setup. |
Customer Vault
The Customer Vault is where financial instruments are related with Customer references and all the sensitive data is encrypted and stored. Imburse offers the right to be forgotten (in line with GDPR requirements), deleting the encryption keys that protect the sensitive data.
Customer Ref
This is a unique customer reference. It should be mapped to a customer identifier/number on your side, and act as your customer representative on Imburse. It should not contain any personal identifiable information of the customer.
Financial Instruments
Financial Instruments represent a payment method owned by a customer. Examples of Financial Instrument would be a Credit Card number, Bank Account Number, mobile phone number, Direct Debit Mandate, or an Authorized Reward amount.
Financial Instruments may have support for Credit and/or Debit type transactions. There are different ways to create these Financial Instruments, according to the type of operation and payment options desired to provide to the customer.
To learn more about how a Direct Debit Mandate can be created or registered see Mandate Management Tool; Check how a Bank Account Financial Instrument can be created if you need to payout: API Spec link
To learn how Imburse handles Credit Card sensitive customer information in a PCI-DSS compliant manner, please check: link to white label part By using Imburse white label integration, through the incorporation of our Checkout Component, the Financial Instrument for Card Payments is automatically generated within our systems.
The financial instrument consists of the following attributes:
| Field | Description |
|---|---|
| id | Identifier for the financial instrument, generated and controlled by Imburse, guaranteed to be unique for a given customerRef. |
| displayName | Human readable description of the financial instrument, combining its type with the details that make it unique. |
| type | The category that the financial instrument belongs to. It controls the attributes stored within the details property, as well as the payment methods it can support. |
| status | Determines whether the financial instrument can be used on instructions: ACTIVE; or not: CLOSED. |
| details | Attributes specific to the financial instrument’s type. |
| capabilities | Defines the constraints that associated transactions must respect. valueType: FIXED or VARIABLE amounts; usageType: SINGLE or MULTIPLE utilization; canCredit for payouts; canDebit for collections. |
| transactions | Lists any transactions that have used this financial instrument. |
Webhooks
Webhooks, also known as Web Callbacks or an HTTP push API, is a way for an application to provide other applications with near real-time information.
Imburse uses Webhooks to provide you with near real-time notifications to your internal systems, such as when a payment is updated and settled, a mandate is registered, or a chargeback occurs.