Business Identification Service

Overview

The Business Identification Service allows merchants to create a 3-character BIN (Business Identification Number). This BIN is used to identify merchant funds and transactions, ensuring that funds are accurately allocated to the merchant’s wallet from the pool. Merchants can also issue unique client references for better reconciliation and tracking.

Once a merchant has generated a BIN, they can create unique client references for their customers. The format for client references is:

• Client reference must start with the merchant BIN

• Maximum size: 8 characters

• Must be alphanumeric and uppercase

Merchants must instruct their clients to always include the reference in the narration/description field when sending funds to the provided account to ensure proper identification and crediting.

Available currencies

• KES (Kenyan Shilling)

• ZMW (Zambian Kwacha)

• ZAR (South African Rand)

• XOF (beta)

Integration steps

You can generate a BIN and start receiving money in 3 easy steps:

1. Prepare payload

2. Initiate BIN creation

3. Get instant response

Before you begin!

• Link to the Postman collection

• Find your keys on the Klasha Dashboard → Settings → Generate API Keys (here)

• Klasha Dashboard, Generate API Keys page

Authentication

Initiate BIN creation

Generate BIN

POST {{env_url}}/nucleus/foreign-funding/bins?businessId={{businessId}}

You are required to set the x-auth-token and Authorization in the headers.

Headers

Key	Value
x-auth-token	Your merchant public key
Authorization	Bearer <token here>

Request Param

businessId:{{businessId}}

200: Ok

{
    "message": "success",
    "error": null,
    "data": {
        "id": 4,
        "bin": "DL0",
        "businessId": 3,
        "createdAt": "2024-09-17 14:38:28",
        "updatedAt": "2024-09-17 14:38:28"
    }
}

400: Bad request

{
    "message": "Business has already been issued a bin",
    "error": "Bad Request",
    "data": null
}

Get bank account details

GET {{env_url}}/nucleus/foreign-funding/accounts?currency={{currency}}&businessId={{businessId}}

Fetch the bank account details to share with your customers to proceed with funding with narration starting with your generated BIN.

Headers

Key	Value
Authorization	Bearer <token here>

200: Ok

{
    "message": "success",
    "error": null,
    "data": [
        {
            "id": 1,
            "businessId": 176,
            "accountNumber": "0011223344",
            "accountName": "Klasha Ke",
            "bankName": "FBN ltd",
            "currency": "KES",
            "location": "Kenya",
            "isLocationDefault": true,
            "createdAt": "2024-08-09 11:28:13",
            "updatedAt": "2024-08-09 11:28:13"
        }
    ]
}

400: Bad request

{
    "message": "No accounts available for the specified currency USD",
    "error": "NOT_FOUND",
    "data": null
}

Get transaction status

GET {{env_url}}/nucleus/foreign-funding/transactions/{{reference}}

Fetch transaction status using reference/narration shared to your customers.

Headers

Key	Value
Authorization	Bearer <token here>

200: Ok

{
    "message": "success",
    "error": null,
    "data": {
        "id": 24,
        "businessId": 133,
        "walletTransactionId": 12102,
        "amount": 2000.00,
        "fee": 2.00,
        "rate": "1",
        "type": "BANK_TRANSFER",
        "clientReference": "WZ0-CVDSDWEWERFEWRWRWEED",
        "currency": "KES",
        "narration": "MOB2/UTU/From JANET WAMBUI KIRAGU/WZ0-CVDSDWEWERFEWRWRWEED",
        "status": "SUCCESSFUL",
        "uploadedBy": "[e-mail]",
        "senderAccountNumber": "N/A",
        "senderAccountName": "From JANET WAMBUI KIRAGU",
        "senderBankName": "N/A",
        "batchId": "KFF-4109fad5-e2ca-4e2e-99c3-6cd865a8c68b",
        "isSettled": true,
        "dateOnStatement": "2024-08-20",
        "createdAt": "2024-09-13 13:54:27",
        "updatedAt": "2024-09-13 13:54:27"
    }
}

400: Bad request

{
    "message": "No transaction found for clientReference 34",
    "error": "NOT_FOUND",
    "data": null
}

Retrieve BIN

GET {{env_url}}/nucleus/foreign-funding/bins/{{businessId}}

Get your bin using your business id.

Key	Value
Authorization	Bearer <token-here>

200: OK

{
    "message": "success",
    "error": null,
    "data": {
        "id": 3,
        "bin": "WZ0",
        "businessId": 133,
        "createdAt": "2024-08-12 15:11:39",
        "updatedAt": "2024-08-12 15:11:39"
    }
}

400 : Bad Request

{
    "message": "Bin data not found for business 1",
    "error": "NOT_FOUND",
    "data": null
}