Callback

Each time a merchant sends a request (RequestPayment) or Response(BillPayment) to Havanao, and He wants to be informed about transaction status later on, They will have to add a parameter called callback_url to inform Havanao that it should call them back informing them the response. If callback_url is not mentioned in a response or request, Then Havanao will not call merchant endpoint later on.

Note: This supports all payment APIs on Havanao (BillPayment, Cash In / Deposit, PaymentRequest).

Flow for bill payment

After Havanao receives transactcion from finance institution and fire the request to the merchant, He will responds to Havanao with usual response, then add callback_url parameter in the response body.

What merchant should respond to Havanao

{
  "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"
  "callback_url": "https://yourapihost.com/api/v1/billpayment/txn9283"
}

What Havanao should sent to callback url after 30 seconds

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

Flow for Request Payment

The merchant calls Havanao SalesRequest / RequestPayment API, and include callback_url in the request, After one minute Havanao will call provided callback_url and send the transaction status.

Merchant Request to Havanao format

{
  "amount": "500",
  "customer": "250722120101",
  "transactionid": "1231412asdfsd",
  "comment": "Just a comment"
  "callback_url": "https://callback_url.com"
}

Havanao response to merchant

{
  "code": 400,
  "status": "ERROR",
  "transactionid": "TXN5-78F9-0AA5-0699",
  "transactionStatus": "APPROVED",
  "description": "You have already used 12312312sd as transaction id. Please provide a non used transaction id."
}