iHela Client

This is the repository for a Python client for consuming the iHela Crédit Union API for financial services in Burundi. The API gateway can be found on https://testgate.ihela.online/

Get started

Installation

Install the package with pip install ihela-python-client

Get a client instance

import the package for using the provided functions to communicate with the iHela API

from ihela_client import MerchantClient 

CLIENT_ID = "<Your Client ID>"
CLIENT_SECRET = "<Your Client Secret>"
PROD_ENV = False

cl = MerchantClient(CLIENT_ID, CLIENT_SECRET, prod=PROD_ENV)
redirect_uri = "https://yourapp.com/uri/to/redirect/to/"

Set PROD_ENV = True for production, otherwise set it to PROD_ENV = False The redirect_uri must be registered with the client created by iHela both for test and production. This is not mandatory.

Bank list

This returns the banks list for getting their slugs for the requests.

# cl.init_bill(AMOUNT, USER_EMAIL, TRANSACTION_DESCRIPTION, MERCHANT_REFERENCE, BANK, BANK_CLIENT_ID,redirect_uri=URL)
banks = cl.get_bank_list()

The bank list response gives the bank information that can help you provide a complete widget on your side (name, type, different codes, logo and icon, ...)

{
    "banks": [
        {
            "slug": "MF1-0001",
            "name": "iHela Credit Union",
            "swift_code": None,
            "bank_code": 1,
            "bank_type": "MF1",
            "can_create_account_online": True,
            "is_active": True,
            "company": {
                "name": "Ihelá Credit Union",
                "fullname": "Ihelá Credit Union",
                "nickname": "ICU",
                "slug": "ihela-credit-union",
                "image": "https://testgate.ihela.online/vwmedia/addressbook/companies/ihelalogo_DCklq5H.jpg",
                "about": "Ihelá Credit Union",
                "logo": "https://testgate.ihela.online/vwmedia/addressbook/companies/ihelalogo_DCklq5H.jpg",
                "logo_icon": "https://testgate.ihela.online/vwmedia/addressbook/companies/icon/ihelacreditunionfondblanc.png",
            },
            "limits_config": None,
            "account_masked_text": "000000-00",
            "ihela_account_inside": None,
        },
        {
            "slug": "MOB-0003",
            "name": "EcoCash",
            "swift_code": None,
            "bank_code": 3,
            "bank_type": "MOB",
            "can_create_account_online": False,
            "is_active": True,
            "company": {
                "name": "EcoCash",
                "fullname": "EcoCash",
                "nickname": None,
                "slug": "ecocash",
                "image": "https://testgate.ihela.online/vwmedia/addressbook/companies/logoEcoCash.gif",
                "about": "",
                "logo": "https://testgate.ihela.online/vwmedia/addressbook/companies/logoEcoCash.gif",
                "logo_icon": "https://testgate.ihela.online/vwmedia/addressbook/companies/icon/logoEcoCash_LfUl0cA.gif",
            },
            "limits_config": None,
            "account_masked_text": "00000000",
            "ihela_account_inside": None,
        },
        {
            "slug": "MOB-0006",
            "name": "PesaFlash",
            "swift_code": None,
            "bank_code": 6,
            "bank_type": "MOB",
            "can_create_account_online": False,
            "is_active": True,
            "company": {
                "name": "Pesaflashjklfs",
                "fullname": "Pesaflashjklfs",
                "nickname": "-",
                "slug": "pesaflashjklfs",
                "image": "https://testgate.ihela.online/vwmedia/addressbook/companies/FINBANK_LANDSCAPE_MxkUXas.png",
                "about": "Pesaflash",
                "logo": "https://testgate.ihela.online/vwmedia/addressbook/companies/FINBANK_LANDSCAPE_MxkUXas.png",
                "logo_icon": "https://testgate.ihela.online/vwmedia/addressbook/companies/icon/FINBANK_LANDSCAPE_A0DFqu8.png",
            },
            "limits_config": {
                "in_minimum": "10000.00",
                "in_maximum": "50000000.00",
                "out_minimum": "10000.00",
                "out_maximum": "50000000.00",
            },
            "account_masked_text": None,
            "ihela_account_inside": None,
        },
    ],
    "count": 3,
    "response_status": 200,
}

Customer Lookup

We will make a customer lookup for having the account number to use in the cashin function.

# cashin = cl.cashin_client(BANK_SLUG, ACCOUNT_NUMBER, AMOUNT, MERCHANT_REFERENCE, TRANSACTION_DESCRIPTION)
customer_lookup = cl.customer_lookup(bank_slug=selected_bank["slug"], customer_id="76000111")

And you get the acccount_number :

{'account_number': '000001-01', 'name': 'Bigirimana Fabrice', 'response_status': 200}

The name can be prompted so that the user can confirm there is no error.

Initialize Bill

Call bills functions as shown below. The function accepts the user email, user phone number or user ihela id

# cl.init_bill(AMOUNT, USER_EMAIL, TRANSACTION_DESCRIPTION, MERCHANT_REFERENCE, BANK, BANK_CLIENT_ID,redirect_uri=URL)
bill = cl.init_bill(2000, "[email protected]", "My description", "unique_reference", redirect_uri=redirect_uri)

BANK and BANK_CLIENT_ID are optional, They are used when the transaction is made from a third party Bank or Institution.

bank_slug = selected_bank["slug"]

# cl.init_bill(AMOUNT, USER_EMAIL, TRANSACTION_DESCRIPTION, MERCHANT_REFERENCE, BANK, BANK_CLIENT_ID,redirect_uri=URL)
bill = cl.init_bill(2000, "76000111", "My description", "unique_reference", bank=bank_slug, bank_client_id="76000111", redirect_uri=redirect_uri)

Here is a response sample. You must have a copy of the "code" and the "confirmation_uri" and other data you judge important. The confirmation_uri provides a direct url to the bill in iHela. You can directly redirect the user to.

{
	"bill": {
	    "merchant": {
	        "title": "Global Test Merchant",
	    },
	    "amount": "2000.00",
	    "currency": 108,
	    "currency_info": {
	        "iso_code": 108,
	        "iso_alpha_code": "BIF",
	        "title": "BURUNDIAN FRANC",
	        "abbreviation": "BIF",
	        "operation_min_amount": "1.00"
	    },
	    "description": "Global Test Merchant (1) My description 58646cc904c471d6413e",
	    "merchant_reference": "58646cc904c471d6413e",
	    "status": {"label": "Initiated", "value": "I", "css": "tag is-info"},
	    "expired": False,
	    "code": "BILL-20200813-B8GUIUDIN0",
	    "redirect_uri": None,
	    "confirmation_uri": "https://mytest.ihela.online/u/operations/bill/confirm/BILL-20200813-B8GUIUDIN0",
	    "payment_reference": None,
	    "created_at": "2020-08-13T10:24:58.014322Z"
	},
	"response_status": 200
}

Verify a bill

You can then verify after if the user has paid the bill in iHela. (NB: He must go to iHela and pay). You can provide a background task or a reload button in your interface for checking.

cl.verify_bill(bill["bill"]["merchant_reference"], bill["bill"]["code"])

Here is a response sample. Bill can be Pending, Paid or Expired. If bill is paid, "bank_reference" will return the transaction reference in the bank.

{
    "bill": {
        "bank_reference": None,
        "reference": "BILL-20200813-B8GUIUDIN0",
        "code": "58646cc904c471d6413e",
        "status": "Pending"
    },
    "response_status": 200
}

Cashin client account

If your client has to be refunded or gratified directly in this account in our system, use the cashin operation. The variable customer_lookup is from the client lookup function here above.

# cashin = cl.cashin_client(BANK_SLUG, ACCOUNT_NUMBER, AMOUNT, MERCHANT_REFERENCE, TRANSACTION_DESCRIPTION)
cashin = cl.cashin_client("MF1-0001", customer_lookup["account_number"], 20000, "REF3223", "Cashin description")

Here is a response sample

{
    "bank_slug": "MF1-0001",
    "account": "000001-01",
    "amount": "20000.00",
    "description": "Cashin description",
    "merchant_reference": "REF3223",
    "error": false,
    "error_message": "Success",
    "reference": "CPT-5/01-199",
    "response_status": 200,
}