# Merchant Bulk Transfer

## Initiate Merchant Bulk Transfer

{% hint style="info" %}
For this API,  whitelisting of the partner's merchant account (i.e., `payerAccountId`)  needs to have been arranged beforehand. Available only to licensed partners.
{% endhint %}

Use this API to disburse funds from your merchant accounts to other Choice Bank accounts (internal transfer) as well as external. All KES accounts of a whitelisted payment institution/service provider can be used for transitional fund settlement, and no OTP validation is required for transfers from that account to the beneficiaries, no matter which bank they are in. 

<mark style="color:green;">`POST`</mark> `/trans/batchTransitionalFundsDisbursement`

<table><thead><tr><th width="166.20013427734375">Paramaters</th><th width="88.39990234375">Type</th><th width="380.3997802734375">Description</th><th>Required?</th></tr></thead><tbody><tr><td><code>payerAccountId</code></td><td>string</td><td><p>Allow merchant account only </p><p></p><p>Verification: the merchant account must be associated with a BaaS channel, otherwise the request will fail</p></td><td>Mandatory</td></tr><tr><td><code>orgBatchId</code></td><td>string</td><td>The unique batch ID generated by the merchant for this bulk payment request</td><td>Optional</td></tr><tr><td><code>beneficiaryArray</code></td><td>array</td><td>Array of the beneficiary details</td><td>Mandatory</td></tr><tr><td>Beneficiary Details/Array</td><td></td><td></td><td></td></tr><tr><td><code>orgTxId</code></td><td>string</td><td>The unique transaction ID generated by the merchant for this specific transaction.</td><td>Optional</td></tr><tr><td><code>payeeAccountName</code></td><td>string</td><td>Payee account name</td><td>Mandatory</td></tr><tr><td><code>payeeAccountId</code></td><td>string</td><td><p>Payee account number </p><p></p><p>If Mpesa Pay Bill/Till, use the specific account or till number</p></td><td>Mandatory</td></tr><tr><td><code>payeeBankCode</code></td><td>string</td><td>Refer to <a href="https://n05mxbyps1.feishu.cn/sheets/shtcnFyw3Kroc5tHUniyUaEptwf?sheet=5f853e">Choice BaaS Bank Code List</a> Kenya Bank Code and Wallet Entities tab.</td><td>Mandatory</td></tr><tr><td><code>payeeType</code></td><td>string</td><td><p>0 for Individual</p><p>1 for Business<br></p><p><code>payeeType</code> only be mandatory if <code>payeeBankCode</code> is M-PESA, otherwise it's optional.</p></td><td>Conditional<br></td></tr><tr><td><code>payType</code></td><td>string</td><td><p>0 for Pay Bill</p><p>1 for Pay Till</p></td><td>Optional<br></td></tr><tr><td><code>payeeSubAccount</code></td><td>string</td><td>For Paybill cases</td><td>Optional</td></tr><tr><td><code>currency</code></td><td>string</td><td>Allow KES only for now</td><td>Mandatory<br></td></tr><tr><td><code>amount</code></td><td>string</td><td>Amount to be transferred</td><td>Mandatory</td></tr><tr><td><code>paymentPurpose</code></td><td>string</td><td>Purpose of bank transfer (Use <a href="/pages/4hf154TLvXNMqvQbYRAl#pesalink-codes">PesaLink Codes</a>)</td><td>Optional</td></tr><tr><td><code>remark</code></td><td>string</td><td>Message to the beneficiary<br><br>For transfers to Airtel Money, remark should not have any special characters and should be alphanumeric and max length is 64 characters. </td><td><br></td></tr><tr><td><code>payeeMobileForNotification</code></td><td>string</td><td>The mobile number of the beneficiary of the sms notification to remind beneficiary of this inbound.<br></td><td>Optional</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="00000" %}

```json
{
  "orderId": ""
}
```

{% endtab %}
{% endtabs %}

**Result:** Please refer to callback [0004 - Merchant Bulk Fund Transfer Result Notification](https://choice-bank.gitbook.io/choice-bank/notifications/callback-notifications#id-0004-merchant-bulk-transfer-result)

## Query Merchant Bulk Transfer Details

<mark style="color:green;">`POST`</mark> `/trans/getInternalBatchTransactionResult`

\<Use this endpoint to query merchant account details>

**Parameters**

<table data-full-width="false"><thead><tr><th width="152.4000244140625">Parameters</th><th width="85">Type</th><th width="290">Description</th><th width="161.9332275390625">Required?</th></tr></thead><tbody><tr><td><code>orderId</code></td><td>string</td><td>The <code>orderId</code> returned by Choice</td><td>TRUE</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="00000" %}

```json
{
  "orderId": "",
  "resultArray": [
    {
      "payeeAccountId": "",
      "payeeAccountName": "",
      "payerAccountId": "",
      "payeeType": "",
      "currency": "",
      "amount": "",
      "txId": "",
      "txStatus": "",
      "completedTime": ""
    }, {}
  ]
}
```

{% endtab %}
{% endtabs %}

## Query Merchant Account Details

<mark style="color:green;">`POST`</mark> `/query/getMerchantAccountDetails`

\<Use this endpoint to query merchant account details>

**Parameters**

<table data-full-width="false"><thead><tr><th width="258">Parameters</th><th width="85">Type</th><th width="306">Description</th><th width="99">Is Required</th></tr></thead><tbody><tr><td><code>accountId</code></td><td>string</td><td>Merchant account number</td><td>TRUE</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="00000" %}

```json
{
  "accountId": "",
  "accountName": "",
  "customerId": "",
  "currency": "",
  "accountType": "",
  "shortCode": "",
  "createTime": "",
  "balance": "", //available balance
  "frozenBalance": "",
  "dormantStatus": "", //0-Normal; 1-Dormant
  "abnormalStatus": "",//0-Normal; 1-Dormant; 2-Restricted; 3-Frozen
  "restrictStatus": "",//0-Normal; 1-Restrict In; 2-Restrict Out
  "freezeStatus": "", //0-Normal; 1-Frozen;
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://choice-bank.gitbook.io/choice-bank/merchant/merchant-bulk-transfer.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.