Getting Started with Imburse

Imburse platform lets you collect money or payout or rewards. But, you might be eager to see how it works. This Getting Started guide is designed to walk you through the quickest and simplest steps that you can follow to see the core functionality of the platform.

Who this guide is for?

If you are just starting your journey with the Imburse platform and are eager to learn what Imburse platform can do for you, this guide is for you. This guide is also for you if you want to refresh you knowledge on the basic functionality of the Imburse platform.

Who this guide is not for?

If you want to explore all the features available in the Imburse platform, this guide is not for you. See User Guide for in-depth information on the features available in the Imburse platform.

Before you start

Before you start using this guide there are a few prerequisites that you will need to meet. Some of the following prerequisites, as "Setup an Account" and "Setup a Tenant" might only be required once. If you have already completed the following setup, you can directly jump to the 4-Steps that Demonstrate the Imburse Plaform.

Understand Imburse-related Terms

This guide assumes that you are familiar with the basic terminologies used throughout the Imburse platform. See our Concepts page for a list of all the terminologies used in the Imburse platform.

Setup an Account for Account API Key

When you complete your registration with Imburse, you will receieve an Account. You will have to setup your Account to obtain Account API Key.

Setup a Tenant

You can create as many Tenants as you need.

Once you have an Account, you must setup at least one Tenant. Setting up a Tenant usually involves the following:

4-Steps that Demonstrate the Imburse Plaform

At Imburse, we believe in experimenting with the product, in addition to reading guides about it. We invite you to perform the following 4-steps so that you can feel even more confident about our capabilities.

Authenticate your Identity
Create an Order and Instruction
Load Checkout Component
Get Transaction Status

Step 1: Authenticate your Identity

Just as you would require a password to access your email address or a key to unlock the door at your house, Imburse also requires a key from you before you can access any Imburse features. Imburse uses this key to prevent anyone who doesn't have access to your tenant from accessing your information. Imburse uses industry-standard HMAC token to generate the key (Access Token) that will be used to authenticate your requests.

Create and Obtain your Tenant API Key.

Tenant API Key and Account API Key are two different concepts.

Generate the HMAC Token
Create an Access Token by sending the HMAC Token to our /v1/identity/hmac endpoint
Use the Access Token in the Authorization header of your following API requests

For full context about authentication used on Imburse API requests check UserJourney : Authenticate your API Requests

Step 2: Create Instruction(s) and Order

Whether you want to pay out, collect a one-off payment or collect recurrently, the payment intent to transact with Imburse starts with Instruction(s) and an Order that can aggregate the Instruction(s). Instructions, as the name suggests, are the rules (e.g., how much to collect/pay, when to collect/pay, currency) that Imburse will follow to complete a transaction. An Order is a group of these instructions.

Get the schemeId from one of the schemes you created while setting up the Tenant.
Follow the API Reference documentation on Create Instruction to create the request body for Instruction(s) using the schemeId

Set the direction property to Debit for collection and Credit for rewards payout.
To collect recurrently or schedule future payments, set the value of the settledByDate property to the date when Imburse should process the payment.

Follow the API Reference documentation on Create Order to create the request body for the Order that will group the Instruction(s) you've created.

Step 3: Load Checkout Component

Orders and Instructions define the details of transaction. To complete the transaction, your customers must provide the details of the Financial Instrument they want to use. Imburse platform offers Checkout component (a secure and user-friendly interface) that you can present to your customer to collect the details of their Financial Instruments.

Use the orderRef value you had set while creating Orders and instructionRef value you had set while creating Instructions to create request body for generating Session Token.
Load the Checkout Component using the Session Token and present it to your customers.

When a customer submits the details of their Financial Instruments, Imburse will automatically fill the financialInstrumentId property in the original Instruction that was used to generate the Session Token. You can reuse the financialInstrumentId for future Instructions against the payments with the same details and the same customer. Set the settledByDate property in future Instructions to reuse the financialInstrumentId.

Step 4: Get Transaction Status

Once your customer submits the Financial Instrument and the Payment Service Provider processes the submission, you will be curious to know whether the transaction was successful. Imburse provides two different methods to get a report on the status of your transaction.

While you can opt for only one of the following two methods, we strongly suggest that you use both the methods for a more robust solution.

API Polling

You can autonomously poll our Get Instruction endpoint to receive a response that contains the information about the state of the transaction. You can also poll this endpoint to get the information about the transaction as it passes through the various states of the payment cycle.

Webhook Notifications

If you don't want to poll the Get Instruction endpoint but rather want near real-time notifications to inform you once the transaction has reached its final state, configure webhooks to send you notification. You can also configure webhooks to send you notification as the transaction progresses through different states of payment cycle.