Getting Started with Imburse
This Getting Started tutorial includes an end-to-end process of five starter tasks to help you get started with Imburse product. The guide explains and shows how to use an Imburse product to receive the simplest and easiest result, so you get an end-to-end sense of how it works.
At Imburse, we believe that learning by doing and experimenting with the system can help to understand the product and feel confident with it rather than reading long walls of text.
To get you ready to collect money or payout rewards, follow our Getting Started tutorial listing five steps:
- Create and set up your Tenant
- Authenticate
- Create an Order and Instruction
- Load Checkout Component
- Get Payment Report
Before you start
Make sure the following prerequisites are met:
- An account setup and
Account API Key
consisting of a public key and private key. You will be provided with the account setup along with the keys upon your registration with Imburse. For more information on what an account is, see Concepts: Account. - The following topics are written with the assumption that you are familiar with the Imburse basic Concepts.
Step 1: Create and set up your Tenant
- Access your account either through the Account portal or by using its REST API directly at the Imburse API platform.
- Create and add a Tenant to allow these users to log into the portal. To do so, in the Account portal navigate to the left-sidebar menu and select Tenants. You can create as many Tenants as you need
- Login into your Tenant and perform the following configuration activities before starting to transact with Imburse:
- Navigate to the Marketplace to add and configure your desired App(s). For more information, see Marketplace.
- Go to the Scheme section and create a scheme for collecting, paying out, or adding your already installed App to the Scheme. For more information, see Collect and Payout.
- Navigate to the Developers section to create your first API Key. For more information, see Developers Section.
Now, you are ready to start playing with our API.
Step 2: Authenticate
You can authenticate your access to Imburse by using the JSON Web Token (also known as JWT) string. This token is generated with an HMAC signed request along with your public and private keys sent to our Authentication API.
- To learn more on how to authenticate, see Authentication.
- To generate HMAC token by using our online form, see Create HMAC Token.
- To see an example on the HMAC generation, see Examples repository.
Step 3: Create Order and Instruction(s)
Whether you want to pay out, collect a once-off payment or collect recurrently, the payment intent to transact with Imburse starts with the Order and its Instructions. For more information, see Concepts: Order & Instructions.- To create your Order and Instruction(s), you need to fetch the
schemeId
from your Scheme created on the Tenant Portal. This is how Imburse knows which PSP to route your payment to. - To collect money, create Debit Instructions.
- To pay out rewards, create Credit Instructions.
- To collect recurrently and schedule future payments, create the instructions for the future payments with the
settledByDate
of when you want the payment to be processed.
Step 4: Load Checkout Component
With the Imburse Checkout component, you can collect payment details securely and seamlessly.
- When your order and instruction are created, you will be able to generate your session token.
- After that, you are ready to load the Checkout and present it on your front end.
- When the Checkout form is submitted, the instruction used to generate the session token before will be populated with
financialInstrumentId
. This financial instrument ID can be reused for future payments against the same payment details introduced in the checkout.
Step 5: Get Payment Report
When the payment is created – Order & Instructions plus the Financial Instrument –, and it has been processed by the PSP, the final step is to know whether it was successful or not. Imburse offers two options to get the report of the payment, and we suggest you implement both to have a more robust solution:
- GET Method
With this option, you are autonomous to poll the API and receive a response containing the state of the instruction. The instruction, representing the payment, will inform you of the state of the transaction throughout its cycle. Search for the payment by its Order and Instruction using the GET Instruction Method.
- Notifications
This option enables your system to receive real-time notifications of several other events as well as once the payment has reached its final state, is to configure webhook notifications. Check the section on Notifications to learn how to configure them, which events you receive notifications of, and many more.