Create Order and Instructions

We recommend that you use the sandbox environment for accessing the APIs, if you are trying to create Orders and Instructions for the first time.

This document outlines the generic process associated with Orders and Instructions. For specific use case, visit the Use Case section of this site.

Order and Instructions sit at the very heart of the Imburse platform. They inform the platform about your intention to collect or payout your customers.

The Imburse platform lets you leverage the flexibility of JSON based objects to create Orders and Instructions. You can then pass the JSON objects through our Order Management APIs to start making payments or collections.

Follow this guide to the end to learn all about Orders and Instructions in the Imburse platform.

Before you Start

Before you start following this guide, we assume that you understand the concepts related to the Imburse platform. We also assume that you have created the Scheme you want to use.

How it works?

After you have constructed the JSON object for Orders and Instructions and made a call to our Order Management APIs, the Imburse platform creates Orders and Instructions within Imburse.
Then, you request a checkout token (or a Pay-By-Link object) through our White-Label service APIs.
You will have to embed the token to your checkout UI component or send the the link to your customers.
The user will then submit their Financial Instrument details through the UI components and Imburse will communicate with the Payment Service Provider (PSP) to handle the transaction.
Once the transaction is complete, a notification will be sent through the Webhook. If you haven't setup a Webhook, you can poll our APIs to check if the transaction has been completed.

How to Process Order and Instructions?

If you are trying to create Orders and Instructions for Payout using the Imburse APIs, you must create relevant Financial Instrument before proceeding with the steps below.

Step 1: Authenticate yourself

The first step in creating Order and Instructions start by authenticating yourself. See Auhthenticate your API Requests for more information.

Step 2: Define your payment intention

You can define your payment intention by constructing request body for our create-order endpoint and making a call to the endpoint. This endpoint is a part of our Order Management APIs. Follow our API documentation to learn more about the properties associated with the endpoint.

You can find the schemId from the Tenant portal by clicking on the Scheme you want to use with payment intention.

You must set the value of the financialInstrumentId property in the request body, if you are constructing payment instruction for Payout. You must also set the value of the direction property to Credit.

Request Body SyntaxRequest Body Example CollectionRequest Body Example Payout

Copy

Copied

{
  "orderRef": "<string>",
  "instructions": [
    {
      "instructionRef": "<string>",
      "customerRef": "<string>",
      "direction": "<string>",
      "FinancialInstrumentId": "<string>",
      "amount": "<currency>",
      "currency": "<string>",
      "country": "<string>",
      "schemeId": "<string>",
      "settledByDate": "<Date in ISO 8601 format>",
      "metadata": {
        "<customField>" : "<string>"
        ...
      }
    }
  ]
}

Copy

Copied

{
  "orderRef": "order_Collect_01",
  "instructions": [
    {
      "instructionRef": "PAYMENT-01",
      "customerRef": "customer_01",
      "direction": "DEBIT",
      "FinancialInstrumentId": "",
      "amount": "10.00",
      "currency": "GBP",
      "country": "UK",
      "schemeId": "4E1E8D9F022E7A6A09FAEB71992E7F2F",
      "settledByDate": "2022-12-01",
      "metadata": {
      }
    }
  ]
}

Copy

Copied

{
  "orderRef": "order_Payout_01",
  "instructions": [
    {
      "instructionRef": "PAYMENT-01",
      "customerRef": "customer_01",
      "direction": "CREDIT",
      "FinancialInstrumentId": "9cb4aab7-5cbe-012c-c345-00c118e66696",
      "amount": "10.00",
      "currency": "GBP",
      "country": "UK",
      "schemeId": "62518C8474D3C5472DDCAF51C2136412",
      "settledByDate": "2022-12-06",
      "metadata": {
      }
    }
  ]
}

Step 3: Call Imburse's White-label service API

If you are trying to create Orders and Instructions for Payout using Imburse APIs, you need not complete Step 3: Call Imburse's White-label service API.

After you have created an intention for payment, you need to direct your customers to the UI where they will enter their Financial Instrument detail. For that reason, you will have to associate the intention with the UI. You can choose either of the following options to associate the intention with the UI.

Request a session token and embed it to the webpage that will hold the Imburse's checkout UI.
Send a link generated by our Pay-By-Link endpoint.

The billing details in the request body of Create session token endpoint are optional. The values of the orderRef and instructionRef properties should be the the same as in Step 2: Define your payment intention.

Step 4: Check the Payment Status

After the Financial Instrument details of your customer has been submitted to the Imburse platform, Imburse will communicate with the Payment Service Provider (PSP) to handle the transaction. You can check the status of the transaction by polling our APIs. Alternatively, you can also set up a Webhook to notify you once the transaction has been completed.

Troubleshooting

What do I do with the checkout token?

You can embed the checkout token into the iFrame of your website. See Embed Checkout Token for more information.

My transaction has failed. Can I retry using the same Order and Instructions?

You can retry using the same Order and Instructions. However, ensure that the details provided in the intetion are correct.