# New Features

## Transaction Reversal

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

This endpoint allows end users to request for a reversal for a transaction.

**Parameters**

<table data-full-width="false"><thead><tr><th width="177.533203125">Parameters</th><th width="86.199951171875">Type</th><th width="389.4000244140625">Description</th><th>Required?</th></tr></thead><tbody><tr><td><code>transactionId</code></td><td>string</td><td><p>The unique string generated by BaaS platform to identify a transaction. </p><p>It has to be in the last 1 month. The transaction completed over 1 month ago cannot be reversed.</p></td><td>TRUE</td></tr><tr><td><code>reversalReceiptNo</code></td><td>string</td><td>If the transaction has been reversed already from third party institutions (i.e. M-PESA), end users should fill in the receipt number of the reversal transaction (The new transaction created to counter-effect the original one)</td><td>FALSE</td></tr><tr><td><code>reversedTime</code></td><td>string</td><td>If the transaction has been reversed already from third party institutions (i.e. M-PESA), end users should fill in the reversed time of the new reversal transaction</td><td>FALSE</td></tr><tr><td><code>reversalReason</code></td><td>string</td><td>Reversal reason</td><td>FALSE</td></tr><tr><td><code>voucherBase64</code></td><td>string</td><td>Voucher document</td><td>FALSE</td></tr><tr><td><code>voucherType</code></td><td>string</td><td><p>pdf </p><p>image</p></td><td>FALSE</td></tr></tbody></table>

**Response**

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

```json
{
  "applicationId": "",
}
```

{% endtab %}
{% endtabs %}

### Query Reversal Request Details&#x20;

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

Use this endpoint to fetch reversal request details.&#x20;

**Parameters**

<table data-full-width="false"><thead><tr><th width="219">Parameters</th><th width="83">Type</th><th width="307">Description</th><th>Required?</th></tr></thead><tbody><tr><td><code>applicationId</code></td><td>string</td><td>The unique string generated by BaaS platform to identify the application</td><td>TRUE</td></tr></tbody></table>

**Response**

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

```json
{
  "applicationId": "",
  "transactionId": "",
  "reversalReceiptNo": "",
  "reversedTime": "",
  "reversalReason": "",
  "voucher": "",
  "status": "",
  "reversalTxId": ""
}
```

{% endtab %}
{% endtabs %}

## Hakikisha (Validate Account)

<mark style="color:green;">`POST`</mark> `/account/validateAccount`

Use this endpoint to ascertain that the intended recipient is correct before making the transfer.&#x20;

<table data-full-width="false"><thead><tr><th width="127.39990234375">Parameters</th><th width="83">Type</th><th width="412.466796875">Description</th><th>Required?</th></tr></thead><tbody><tr><td><code>accountId</code></td><td>string</td><td>The account/shortcode which the user wants to validate. <br><br>This endpoint does return <code>freezeStatus</code> and <code>restrictStatus</code> as well.</td><td>TRUE</td></tr><tr><td><code>accountType</code></td><td>int</td><td><p>The type of the counterparty account: <br><br>0 - <strong>Choice Bank (internal)</strong> </p><p>1 - <strong>M-PESA Paybill</strong></p><p>2 - <strong>M-PESA Till</strong></p><p>3 - <strong>Mpesa Mobile</strong></p><p>4 - <strong>Pesalink (external bank)</strong></p></td><td>TRUE</td></tr><tr><td><code>bankCode</code></td><td>string</td><td><p>See full list by calling <code>/staticData/getBankCodes</code></p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Mandatory when <code>accountType</code> is 4</p></div></td><td>Conditional</td></tr></tbody></table>

**Response**

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

```json
"data": {
    "accountType": "", //int, account type
    "accountId": "", //String, account Id
    "accountName": "", //String, return the account name if it's a valid accountId
    "freezeStatus":"", //freezeStatus: 0-normal; 1-frozen
    "restrictStatus":"",//restrict status 0-normal; 1-restrict in; 2-restrict out
}
```

{% endtab %}
{% endtabs %}

## Pull Transaction IDs

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

This API is for BaaS partners to get all transaction IDs within a certain period of time so that they do not miss any inbound transactions when balance change notifications / callback is not received.

{% hint style="info" %}
Allowed query data timespan: past 30 days\
Allowed query interval: 1 hour\
Maximum `endTime` to  `startTime` span: 4 hours
{% endhint %}

<table><thead><tr><th width="112.7999267578125">Fields</th><th width="124.5999755859375">Type</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><code>startTime</code></td><td>Long</td><td>Unix timestamp of the start time</td><td>Mandatory</td></tr><tr><td><code>endTime</code></td><td>Long</td><td>Unix timestamp of the end time</td><td>Mandatory</td></tr></tbody></table>

**Response**

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

```json
{
  "transactionID": "00000" //returns list of transaction IDs
}
```

{% endtab %}
{% endtabs %}

## Query Channel Closing Balance

<mark style="color:green;">`POST`</mark> `/report/queryClosingBalance`

Use this endpoint to fetch the consolidated balance across all accounts under your BaaS channel on a certain date.&#x20;

**Parameters**

<table data-full-width="false"><thead><tr><th width="219">Parameters</th><th width="83">Type</th><th width="307">Description</th><th>Is Required</th></tr></thead><tbody><tr><td><code>queryDate</code></td><td>string</td><td>UTC date as at which the closing balance is being sought.</td><td>TRUE</td></tr></tbody></table>

**Response**

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

```json
{
  "jobId": "",
}
```

{% endtab %}
{% endtabs %}

**Result**

Please refer to [0015-File Job Notification](/choice-bank/notifications/callback-notifications.md#id-0015-account-statement-notification)&#x20;


---

# 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/transfer/new-features.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.