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.