Handle webhook

All things event

When a payment occurs, Bani sends a webhook event to the webhook URL that you saved on your dashboard.

It is highly recommended that you use webhooks or verify the payment transaction status before delivering value to your customers.

We advise you to verify the response before carrying out any further action.

Please note: if the payout_status value is 'system_closed', kindly wait until the status change to either 'failed' or 'completed' before taking action on your end.

To verify the response, you will have to form the signature and compare your result with the value of 'BANI-HOOK-SIGNATURE' sent to you. The signature is a combination of your merchant_private_key and request payload.

Python

import hmac
import hashlib
import six

my_hook_signature = hmac.new(six.b(merchant_private_key), msg=str(request_payload).encode('utf-8'), digestmod=hashlib.sha256).hexdigest()
if not hmac.compare_digest(my_hook_signature, bani-hook-signature):
    content = {"message":"Invalid signature"}
    return JsonResponse(content, status=400)

JS

app.post("/webhook", (req, res) => {
  const merchant_private_key = "privatekey";
  const headers = req.headers;
  const body = req.rawBody;
  const sig = Buffer.from(headers["bani-hook-signature"] || "", "utf8");
  //Calculate HMAC
  const hmac = crypto.createHmac("sha256", merchant_private_key);
  const digest = Buffer.from(hmac.update(body).digest("hex"), "utf8");
  if (sig.length !== digest.length || !crypto.timingSafeEqual(digest, sig)) {
    return false;
  } else {
    return true;
  }
});

PHP

$requestBody = 'request_payload';
$secret = 'merchant_private_key';

$signature = hash_hmac('sha256', $requestBody, $secret);

echo $signature;

C#

using System;
using System.Security.Cryptography;
using System.Text;

class Program
{
    static void Main()
    {
        string requestBody = "request_payload";
        string merchantPrivateKey = "your_merchant_private_key";

        string signature = ComputeHmacSha256Signature(requestBody, merchantPrivateKey);
        Console.WriteLine(signature);
    }

    static string ComputeHmacSha256Signature(string data, string secret)
    {
        byte[] keyBytes = Encoding.UTF8.GetBytes(secret);
        byte[] dataBytes = Encoding.UTF8.GetBytes(data);

        using (HMACSHA256 hmac = new HMACSHA256(keyBytes))
        {
            byte[] hashBytes = hmac.ComputeHash(dataBytes);
            return BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
        }
    }
}

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;

public class Main {
    public static void main(String[] args) {
        String requestBody = "request_payload";
        String secret = "merchant_private_key";

        String signature = computeHmacSha256(requestBody, secret);
        System.out.println(signature);
    }

    public static String computeHmacSha256(String data, String secret) {
        try {
            Mac hmacSha256 = Mac.getInstance("HmacSHA256");
            SecretKeySpec secretKeySpec = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
            hmacSha256.init(secretKeySpec);
            byte[] hash = hmacSha256.doFinal(data.getBytes(StandardCharsets.UTF_8));
            StringBuilder hexString = new StringBuilder();

            for (byte b : hash) {
                String hex = Integer.toHexString(0xFF & b);
                if (hex.length() == 1) {
                    hexString.append('0');
                }
                hexString.append(hex);
            }

            return hexString.toString();
        } catch (NoSuchAlgorithmException | InvalidKeyException e) {
            e.printStackTrace();
            return null;
        }
    }
}

Ruby

require 'openssl'
require 'digest'

def compute_hmac_sha256(data, secret)
  hmac = OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha256'), secret, data)
  hmac_hex = hmac.unpack1('H*')
  hmac_hex
end

request_body = 'request_payload'
secret = 'merchant_private_key'

signature = compute_hmac_sha256(request_body, secret)
puts signature

Event	Description
payin_mobile_money	Payment made via mobile money
payin_bank_transfer	Payment made via bank transfer
payin_ewallet	Payment made via third party wallet
coin_payment_incoming	An incoming crypto payment
coin_payment_received	Payment made via crypto
payout	A successful transfer to a bank account or mobile money wallet has been completed
payout_reversal	A transfer to a bank account or mobile money wallet you attempted has been reversed
payout_crypto	A successful transfer to a crypto wallet has been completed
payout_crypto_reversal	A transfer to a crypto wallet you attempted has been reversed
collection_service_status	This is sent whenever a payment method/provider is active or inactive. It's just a way of giving you heads-up on when to activate or deactivate the payment method/provider
vas_completed	This will be sent after a successful bill payment transaction
vas_failed	This will be sent after a failed bill payment transaction

Find sample request payload below.

event. payin_mobile_money

{
  "event": "payin_mobile_money",
  "data": {
    "pay_ref": "BNPay-j6bva8xcesc2vrhhh4w1vs51t9xj96",
    "pay_ext_ref": "",
    "holder_first_name": "Star",
    "holder_last_name": "Lord",
    "custom_data": {
      "me": "userr"
    },
    "pay_amount": "30.88",
    "pay_method": "mobile_money",
    "holder_phone": "[phone]",
    "holder_phone_carrier": "safke",
    "order_details": null,
    "holder_currency": "KES",
    "holder_country_code": "KE",
    "pay_status": "paid",
    "holder_account_number": "",
    "pub_date": "2022-04-07T11:32:24.084772Z",
    "modified_date": "2022-04-07T11:32:33.166011Z",
    "holder_bank_name": "",
    "merch_currency": "NGN",
    "merch_amount": "150.00"
  }
}

event. payin_bank_transfer

{
  "event": "payin_bank_transfer",
  "data": {
    "pay_ref": "BNPay-6je71r6y7yd8x0a6pxpp1b2absx56c",
    "pay_ext_ref": "",
    "holder_first_name": "Mac",
    "holder_last_name": "Keita",
    "custom_data": {
      "me": "userr"
    },
    "pay_amount": "150.00",
    "pay_method": "bank_transfer",
    "holder_phone": null,
    "holder_phone_carrier": "",
    "order_details": null,
    "holder_currency": "NGN",
    "holder_country_code": "NG",
    "pay_status": "paid",
    "holder_account_number": "8180000003",
    "pub_date": "2022-04-07T08:27:54.481411Z",
    "modified_date": "2022-04-07T08:31:16.452737Z",
    "holder_bank_name": "Wema Bank",
    "merch_currency": "NGN",
    "merch_amount": "150.00"
  }
}

event. payin_ewallet

{
  "event": "payin_ewallet",
  "data": {
    "pay_ref": "BNPay-ck0rhghzhb8wtaqycmk8b4as2bpdma",
    "pay_ext_ref": "",
    "holder_first_name": "Rodney",
    "holder_last_name": "Jackson-Cole",
    "custom_data": {
      "me": "userr"
    },
    "pay_amount": "150.00",
    "pay_method": "ewallet",
    "holder_phone": "",
    "holder_phone_carrier": "",
    "order_details": null,
    "holder_currency": "NGN",
    "holder_country_code": "NG",
    "pay_status": "paid",
    "holder_account_number": "",
    "pub_date": "2022-04-06T23:10:13.719380Z",
    "modified_date": "2022-04-06T23:12:01.638946Z",
    "holder_bank_name": "",
    "merch_currency": "NGN",
    "merch_amount": "150.00"
  }
}

event.collection_service_status

{
    "event": "collection_service_status",
    "data": {
        "pay_method": "Bank Transfer",
        "pay_provider_name": "Ocean Bank",
        "pay_method_status": "active",
        "pay_currency": "NGN",
        "pay_keyword":["ocean", "000017"],
        "pay_country": [
            "NG"
        ]
    }
}

event.payout

{
    "event": "payout",
    "data": {
        "transaction_note": "Remittance to 0066492583|John Scodo",
        "fiat_amount": "10.00",
        "coin_amount": "0.000000000000000000",
        "transaction_reference": "f6gktkjykamr40mtq13cc76qx",
        "pub_date": "2022-10-23T10:59:48.586327Z",
        "modified_date": "2022-10-23T10:59:48.588187Z",
        "is_done": true,
        "payout_details": {
            "payout_method": "Bank Transfer",
            "receiver_amount": "10.00",
            "receiver_phone": "",
            "receiver_sort_code": "000005",
            "payout_status": "completed",
            "payout_ref": "WMPRM_jeebzavhj3",
            "payout_ext_ref": "WEMBA-1013",
            "payout_receiver_type": "personal",
            "receiver_account_name": "John Scodo",
            "receiver_account_num": "0000010101",
            "receiver_account_type": "",
            "receiver_address": "",
            "receiver_bank_name": "GRANT BANK",
            "receiver_city": "",
            "receiver_currency": "NGN",
            "receiver_personal_num": "",
            "receiver_postcode": "",
            "receiver_state": "",
            "receiver_country_code": "NG",
            "receiver_bank_branch": "",
            "receiver_first_name": "",
            "receiver_last_name": "",
            "pub_date": "2022-10-23T10:59:48.582486Z",
            "modified_date": "2022-10-23T11:21:49.899924Z",
            "is_beneficiary": false
        },
        "source_account_name": "Nest Cafe"
    }
}

event.payout_reversal

{
    "event": "payout_reversal",
    "data": {
        "transaction_note": "Remittance to 0066492583|John Scodo",
        "fiat_amount": "10.00",
        "coin_amount": "0.000000000000000000",
        "transaction_reference": "f6gktkjykamr40mtq13cc76qx",
        "pub_date": "2022-10-23T10:59:48.586327Z",
        "modified_date": "2022-10-23T10:59:48.588187Z",
        "is_done": true,
        "payout_details": {
            "payout_method": "Bank Transfer",
            "receiver_amount": "10.00",
            "receiver_phone": "",
            "receiver_sort_code": "000005",
            "payout_status": "failed",
            "payout_ref": "WMPRM_jeebzavhj3",
            "payout_ext_ref": "WEMBA-1013",
            "payout_receiver_type": "personal",
            "receiver_account_name": "John Scodo",
            "receiver_account_num": "0000010101",
            "receiver_account_type": "",
            "receiver_address": "",
            "receiver_bank_name": "GRANT BANK",
            "receiver_city": "",
            "receiver_currency": "NGN",
            "receiver_personal_num": "",
            "receiver_postcode": "",
            "receiver_state": "",
            "receiver_country_code": "NG",
            "receiver_bank_branch": "",
            "receiver_first_name": "",
            "receiver_last_name": "",
            "pub_date": "2022-10-23T10:59:48.582486Z",
            "modified_date": "2022-10-23T11:21:49.899924Z",
            "is_beneficiary": false
        },
        "source_account_name": "Nest Cafe"
    }
}

event.vas_completed

{
        "event": "vas_completed",
        "data": {
            "amount": "3200.00",
            "biller_customer_item": "12345678910",
            "customer_biller_code": "91 Abodunrin Street 60 313 IfeomaVille",
            "customer_biller_name": "Wale Emeka Sylvester",
            "vas_type": "Bills Payment",
            "customer_phone_number": "[phone]",
            "currency": "NGN",
            "transaction_ext_ref": "",
            "customer_phone_network": "",
            "transaction_status": "completed",
            "main_category": "ELECTRICITY",
            "sub_category": "IKEDC",
            "biller_extra_info": "60114651373352292125|Units Purchased: 5.1",
            "vas_item_name": "",
            "transaction_ref": "BV-xaz8h4c8k7bjwmw",
            "pub_date": "2023-06-11T20:44:51.648453Z"
        }
    }

event.vas_failed

    {
        "event": "vas_failed",
        "data": {
            "amount": "100.00",
            "biller_customer_item": "",
            "customer_biller_code": "",
            "customer_biller_name": "",
            "vas_type": "Mobile Data",
            "customer_phone_number": "[phone]",
            "currency": "NGN",
            "country_code": "NG",
            "transaction_ext_ref": "",
            "customer_phone_network": "glo",
            "transaction_status": "failed",
            "main_category": "mobile_data",
            "sub_category": "glo",
            "biller_extra_info": "",
            "vas_item_name": "GLO-150MB-3",
            "transaction_ref": "BV-am75yb6zf82z0k8",
            "pub_date": "2023-06-11T21:11:26.399568Z"
        }
    }