Bill operations

iHela Credit Union
Search…
iHela Credit Union
Introduction
Getting Started
Basics
General API Endpoints
Merchant services
Bills Payments
oAuth2 Authentication
Bills operations flow
Bill operations
Merchant Cash-in
Agent API Endpoints
Introduction
Bill operations
Here are all bill operations. Initialization and verification are those important for managing the bill system.
post
https://testgate.ihela.online/api/v1/payments/bill/init/
Bill init 
We recommend to store all the received JSON object elements in your system. Here is their explanation :
bank : The bank slug that you can dynamically get from our bank list . This is where we will send the bill for confirmation. The user parameter must then give the customer id in this bank. When this field is null or not mentioned, the system creates the bill in iHela Credit Union. Every time we have a new partnership with a bank (mobile or classic), it will be added automatically to the bank list and you will have nothing to change here.
bank_client_id: The identifier of the client in the bank if the bank is mentioned, for example in EcoCash or PesaFlash, this will be the phone number.
user : The user who will receive the bill in the iHela platform. This field accepts the username, the phone number, the email or the client ID registered in iHela.
confirmation_uri : The iHela URI where the user must confirm the BILL. He has exclusive access to that link at any time. You can redirect him directly if you want. This can be changed in newer releases if your application will be to provide an expiration DateTime value.
code : The BILL unique code, which is not yet the Bill Payment Reference. This is just to identify the uniqueness of a BILL. This must be unique in all databases for a iHela BILL.
payment_reference : This is just null a this step and will be filled after with the iHela Banking Reference for the Bill Payment Operations.
redirect_uri : Your redirect uri (if given) for redirecting the user after the confirmation. We save this to allow the user to Pay the Bill any time after the initiation and then be automatically redirected to your application.
Your redirect_uri must then make a verify call to have the Last Reference (payment_reference) for the BILL as shown bellow.
post
https://testgate.ihela.online/api/v1/payments/bill/verify/
Bill status verification
​
Bill confirmation callback
The merchant application will provide a callback to be used to send to the merchant API when the customer pays the bill.
This is just used if the Merchant provides a link for payment confirmation. Others will prefer to use the bill status verification section here before.
Request sent
Response to return
{
    "merchant_reference": "MERCHANT_REFERENCE",
    "bill_code": "BILL-....",
    "error": false,
    "error_message": "Success",
    "payment_reference": "WEB.BIL-1.01"
}
{
    "error": false,
    "error_message": "Success"
}
We send the merchant reference and the bill code for verification, then the bill status. If the bill has been paid successfully, we send "error": false else we send "error": true. The error_message contains then the reason of the failure.
The response will return "error": true when the merchant can't process the payment on his side. Then we will automatically refund the money to the client.
The payment_reference contains the bank reference of the transaction that can be checked in the merchant account statement. When there is error, it will be send as null. 
Redirect uri
The redirect uri is a link where our system can redirect iHela users after payment. The redirect uri must be registered in iHela system to be accepted in the bill init request. You will usually provide two redirect uri, one for test environment and one for production environment. 
If your system has many redirect uri for each environment, you can provide all to be registered. But the bill init will accept only one redirect uri among them. 
This means, if you have a website that processes different types of payments, you can have two links that handle them. For example : https://yoursite.com/payment1/redirect and https://yoursite.com/payment2/redirect. 
When calling bill init endpoint for your first type of payment, you will send the first link as "redirect_uri": "https://yoursite.com/payment1/redirect" so that we can redirect the user to. When calling bill init for your second type of payment, you will send then the second link "redirect_uri": "https://yoursite.com/payment2/redirect" 
We will pass parameters to the link when redirecting to your link like this : https//yoursite.com/redirect?operation=billpayment&merchant_reference=MERCHANTREFERENCE&bill_code=BILLCODE&paid=true&status=STATUS&bank_reference=PAYMENTREFERENCE  
If there is an error why trying to pay, we will send these parameters : https//yoursite.com/redirect?operation=billpayment&merchant_reference=MERCHANTREFERENCE&bill_code=BILLCODE&paid=false&status=STATUS 
merchant_reference : The reference in your system that you sent when initializing the bill.

bill_code : The bill code received after initializing the bill.

paid : true if the payment was completed successfully, then we will get the bank_reference in parameters. If there was a permanent error, we will send false boolean value.
status : will give the real status of the bill in our system. It can be "Paid", "Processed", "Pending", "Expired"
bank_reference : The payment reference in iHela.
Bills operations flow
Merchant Cash-in
Last modified 7mo ago
Copy link
Outline
post
Bill init
post
Bill status verification
Bill confirmation callback
Redirect uri