# 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 (<mark style="color:orange;">beta</mark>)

#### 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

{% hint style="info" %}

### Before you begin!

* [Link](https://api.postman.com/collections/8963555-635c3c8e-26bf-4ac0-aa04-6aa500691ef5?access_key=PMAT-01J8096AHFACTFV95C58XNJ2GV) to the Postman collection
* Find your keys on the Klasha Dashboard → Settings → Generate API Keys ([here](https://dashboard.klasha.com/settings/keys))
* Klasha Dashboard, Generate API Keys page

<img src="https://257545343-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNw4nU37LIEg41plxXG5u%2Fuploads%2FvBXI8QATrncq17zlRm1P%2Fdashboad-klasha-settings.png?alt=media&#x26;token=1ebaf2b3-7e99-4490-9ede-a660c8d0035c" alt="" data-size="original">
{% endhint %}

{% content-ref url="../overview/authentication" %}
[authentication](https://developers.klasha.com/overview/authentication)
{% endcontent-ref %}

### Initiate BIN creation

## Generate BIN

<mark style="color:green;">`POST`</mark>  <mark style="color:red;">{{env\_url}}</mark>/nucleus/foreign-funding/bins?businessId=<mark style="color:red;">{{businessId}}</mark>

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**

```json
businessId:{{businessId}}
```

{% tabs %}
{% tab title="200: Ok" %}

```json
{
    "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"
    }
}
```

{% endtab %}

{% tab title="400: Bad request" %}

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

{% endtab %}
{% endtabs %}

## Get bank account details

<mark style="color:blue;">`GET`</mark> <mark style="color:red;">{{env\_url}}</mark>/nucleus/foreign-funding/accounts?currency=<mark style="color:red;">{{currency}}</mark>\&businessId=<mark style="color:red;">{{businessId}}</mark>

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> |

{% tabs %}
{% tab title="200: Ok " %}

```json
{
    "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"
        }
    ]
}
```

{% endtab %}

{% tab title="400: Bad request" %}

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

{% endtab %}
{% endtabs %}

## Get transaction status

<mark style="color:blue;">`GET`</mark> <mark style="color:red;">{{env\_url}}</mark>/nucleus/foreign-funding/transactions/<mark style="color:red;">{{reference}}</mark>

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

#### Headers

| Key           | Value                |
| ------------- | -------------------- |
| Authorization | Bearer \<token here> |

{% tabs %}
{% tab title="200: Ok " %}

```json
{
    "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": "stephen@klasha.com",
        "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"
    }
}
```

{% endtab %}

{% tab title="400: Bad request" %}

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

{% endtab %}
{% endtabs %}

## Retrieve BIN

<mark style="color:blue;">`GET`</mark> <mark style="color:red;">{{env\_url}}</mark>/nucleus/foreign-funding/bins/<mark style="color:red;">{{businessId}}</mark>

Get your bin using your business id.

| Key           | Value                |
| ------------- | -------------------- |
| Authorization | Bearer \<token-here> |

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "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"
    }
}
```

{% endtab %}

{% tab title="400 : Bad Request" %}

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

{% endtab %}
{% endtabs %}