Bill payment.

Bill Payment

If you are a merchant and you would like to receive payment through Havanao, you will need to have an api interface that Havanao platform can understand. whenever Havanao receives a payment request from mno(Mobile Network Operator), it shall fire a request to your API with below defined information in the parameters, then your application has to treat the request and give Havanao response with the format defined in the expected sample request section.

Based on the response from merchant application, Havanao will decide whether is should complete the payment if it's successfully or it decline the payment if the merchant api has failed it or responded with ambigious status(timeout etc..).

PLEASE NOTE THAT IF WE DO NOT GET RESPONSE WITHIN A MAXIMUM OF 5 SECONDS,WE TIME OUT AND FAIL PAYMENT.

URL : It is defined in the settings > merchant information tab. HTTP Method : POST

REQUEST FORMAT

You will expect to recieve below request format, it shall be submitted in request body as json.

{
  "transactionid": "TXN5-78BD-962F-19FD",
  "description": "Bill payment for 202413",
  "reference_number": "202413",
  "customer": "250725633591",
  "amount": 1000,
  "payment_method": "TIGOCASH"
}
 {
  "transactionid": "TXN5-78BD-962F-19FD",
  "description": "Bill payment for 202413",
  "reference_number": "202413",
  "customer": "250784835303",
  "amount": 1000,
  "payment_method": "MTN"
}
  {
    "transactionid": "TXN5-78BD-962F-19FD",
    "description": "Bill payment for 202413",
    "reference_number": "202413",
    "customer": "250733934393",
    "amount": 1000,
    "payment_method": "AIRTEL"
  }

EXPECTED SAMPLE SUCCESSFULL RESPONSE

{
  "transactionid": "TXN5-78BD-962F-19FD",
  "reference_number": "202413",
  "code": "200",
  "status": "OK",
  "account_balance": 1000,
  "customer": "250725633591",
  "description": "Mwakoze kongeramo amafaranga 1000. Mufitemo amafaranga 1000.",
  "payment_reference": "03ef025f74f559f7c391ee5df5966d7240dc5180"
}
{
  "transactionid": "TXN5-78BD-962F-19FD",
  "reference_number": "202413",
  "code": "200",
  "status": "OK",
  "account_balance": 1000,
  "customer": "250784835303",
  "description": "Mwakoze kongeramo amafaranga 1000. Mufitemo amafaranga 1000.",
  "payment_reference": "03ef025f74f559f7c391ee5df5966d7240dc5180"
}
You can recieve more details on demand, for example if you need to receive Merchant Code from operator you just need to enabled it from the merchant apis menu under settings, then you shall be receiving the request with merchant_code as a parameter from MNO. so the request would look like following.
{
  "transactionid": "TXN5-78BD-962F-19FD",
  "description": "Bill payment for 202413",
  "reference_number": "202413",
  "customer": "250784835303",
  "amount": 1000,
  "merchant_code": "23021",
  "payment_method": "MTN"
}
{
  "transactionid": "TXN5-78BD-962F-19FD",
  "description": "Bill payment for 202413",
  "reference_number": "202413",
  "customer": "250733934393",
  "amount": 1000,
  "merchant_code": "23021",
  "payment_method": "AIRTEL"
}

BILL DETAILS

Due to different unavoidable reasons, Havanao may send a payment request and not get the response, in this case we put this transaction in doubt mode since we really don't know what happened to this transaction and we cannot confirm whether it was successfully or failed. Therefore Havanao will attempt multiple time to call merchant APIs(Let call it get transaction details) by passing the transactionid issued in the request then Havanao will expect Merchant platform to respond with what happened to the transaction.

EXPECTED RESPONSES STATUS

Parameter Description
OK This confirms that the transaction has been successfully processed
FAILED Transaction has been submited but it has failed at merchant level due to different reasons.
NOT-FOUND Merchant cannot find the provided transactionid, this happens in most cases when transaction timedout before it reaches merchant. in this case Havanao will mark this transaction as failed.

URL : https://merchantapiurl.tld/getbilldetails/:transactionid

HTTP Method : GET

ARGUMENTS

transactionid Unique transaction id, Havanao passed in the request while initiating a bill payment request to a merchant

TO EXPECT REQUEST FORMAT

Havanao will need to submit below similar sample request, then it will expect merchant to respond with below response format.

curl https://merchantapiurl.tld/getbilldetails/1456919152396a16eb0e032af5749d104527f76b 
-u test_merchant_api_key

EXPECTED SUCCESSFULL RESPONSE

{
  "transactionid": "TXN5-78BD-962F-19FD",
  "reference_number": "202413",
  "code": "200",
  "status": "OK",
  "account_balance": 1000,
  "customer": "250725633591",
  "description": "Mwakoze kongeramo amafaranga 1000. Mufitemo amafaranga 1000.",
  "payment_reference": "03ef025f74f559f7c391ee5df5966d7240dc5180"
}
{
  "transactionid": "TXN5-78BD-962F-19FD",
  "reference_number": "202413",
  "code": "200",
  "status": "OK",
  "account_balance": 1000,
  "customer": "25074835303",
  "description": "Mwakoze kongeramo amafaranga 1000. Mufitemo amafaranga 1000.",
  "payment_reference": "03ef025f74f559f7c391ee5df5966d7240dc5180"
}
{
  "transactionid": "TXN5-78BD-962F-19FD",
  "reference_number": "202413",
  "code": "200",
  "status": "OK",
  "account_balance": 1000,
  "customer": "250733934393",
  "description": "Mwakoze kongeramo amafaranga 1000. Mufitemo amafaranga 1000.",
  "payment_reference": "03ef025f74f559f7c391ee5df5966d7240dc5180"
}

SAMPLE ERROR RESPONSE

  {
    "error": {
      "code": "404",
      "status": "NOT-FOUND",
      "message": "Resource Not Found"
    }
  } 

GET HAVANAO BILL PAYMENT STATUS

Sometimes it happens when a merchant wants to know if havanao has charged the customer or not, in that case, the customer application will need to send a get request to havanao api with havanao transaction id, then havanao will respond with below response format.

REQUEST

URL : https://api.havanao.com/api/bills/get/:transactionid?api_token=YOUR_API_TOKEN

HTTP Method : GET

PARAMETERS DEFINITION
Parameter Description
transactionid HAVANAO Transaction ID received in Bill Payment request.
YOUR_API_TOKEN Havanao api token, this is authentication key and it should be kept in safe and secret place

RESPONSE FORMAT

    {
      "code": 400,
      "status": "error",
      "description": "The transaction you are looking for does not exist.",
      "transactionid": "TXN5-8741-37ED-3DCD"
    }

STATUS MEANING

status Description
OK / APPROVED This means that we have charged the customer.
FAILED / ERROR This means that we did not charge the customer

PLEASE NOTE THAT IF THE STATUS OF THE RESPONSE is not OK or APPROVED You should consider it as failed transaction