--- updatedAt: 2026-02-10T11:45:39.000Z --- # Query float balance The **`BEEP.queryFloatBalance`** API function is invoked by Clients to query the float balance for a particular service within the payment gateway. ### Request | Parameter | Type | Description | Required | | :--------------------------- | :----- | :-------------------------------------------------------------------------------------------------------- | :------- | | countryCode | string | Country ISO code letter, i.e., **`KE`**,**`GH`**,**`TZ`** | yes | | payload | object | | | | payload.credentials | object | | | | payload.credentials.username | string | The user name you created on sign-in | yes | | payload.credentials.password | string | The Password you created on signin | yes | | payload.packet | array | | | | payload.packet.serviceCode | string | This is the product code used in identifying the service the customer is consuming e.g. **`TIGOAIRTIME`** | yes | | payload.packet.narration | string | Text to be appended to the request | no | ```json Request { "countryCode": "ZM", "payload": { "credentials": { "username": "testuser", "password": "testpass" }, "packet": [ { "serviceCode": "TIGOAIRTIME", "narration": "TIGOAIRTIME query" } ] } } ``` *** ### Response Once the request has been received by the Beep Payment gateway, the `BEEP.queryFloatBalance` function will return a multidimensional array consisting of two parts, an authStatus, and a results section. The parameters returned are shown in the table below. | Parameter | Type | Description | Required | | :--------------------- | :------ | :---------------------------------------------------- | :------- | | statusCode | String | The status of this transaction within the Beep system | Yes | | message | String | A narration/ description for the status code above. | Yes | | success | Boolean | Success or failed status | Yes | | data | object | Float balance object | Yes | | data.statusDescription | String | A narration/ description for the status code above | Yes | | data.balance | Double | Float balance available. | Yes | | data.floatAccountName | String | The name of the service float account | Yes | | data.currencyCode | string | The ISO code for the transaction currency. | Yes | ```json Response { "statusCode": 418, "success": true, "message": "Processing was successful", "data": { "floatAccountName": "Payouts Demo CFA", "balance": 45346.8, "currencyID": 70, "currencyCode": "KES" } } ``` # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "payouts-queryfloatbalance", "version": "2.0" }, "servers": [ { "url": "https://api-approval.tingg.africa/" } ], "security": [ {} ], "paths": { "/v2/remittance/payments/query-float-balance": { "post": { "summary": "Query float balance", "description": "The **`BEEP.queryFloatBalance`** API function is invoked by Clients to query the float balance for a particular service within the payment gateway.", "operationId": "remittance-query-float-balance", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "countryCode" ], "properties": { "countryCode": { "type": "string", "default": "KE" }, "payload": { "type": "object", "properties": {} } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Success": { "value": "{\n \"authStatus\": {\n \"authStatusCode\": 131,\n \"authStatusDescription\": \"Authentication was successful\"\n },\n \"results\": [\n {\n \"statusCode\": 418,\n \"statusDescription\": \"Float processing was successful\",\n \"balance\": 56000,\n \"floatAccountName\": \"SANDBOXTEST-VODAPESA\",\n \"currencyCode\": \"TZS \"\n }\n ]\n}" } }, "schema": { "type": "object", "properties": { "authStatus": { "type": "object", "properties": { "authStatusCode": { "type": "integer", "example": 131, "default": 0 }, "authStatusDescription": { "type": "string", "example": "Authentication was successful" } } }, "results": { "type": "array", "items": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 418, "default": 0 }, "statusDescription": { "type": "string", "example": "Float processing was successful" }, "balance": { "type": "integer", "example": 56000, "default": 0 }, "floatAccountName": { "type": "string", "example": "SANDBOXTEST-VODAPESA" }, "currencyCode": { "type": "string", "example": "TZS " } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Bad Request": { "value": "{\n \"authStatus\":{\n \"authStatusCode\":131,\n \"authStatusDescription\":\"Authentication unsuccessful\"\n },\n \"results\":[\n {\n \"statusCode\":167,\n \"statusDescription\":\"Bad Request - countryCode is missing\",\n \"beepTransactionID\":-1,\n \"invoiceNumber\":\"\",\n \"payerTransactionID\":\"ec99b106-6cb7-4394-a510-1f53597a6a17\"\n }\n ]\n}" } }, "schema": { "type": "object", "properties": { "authStatus": { "type": "object", "properties": { "authStatusCode": { "type": "integer", "example": 131, "default": 0 }, "authStatusDescription": { "type": "string", "example": "Authentication unsuccessful" } } }, "results": { "type": "array", "items": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 167, "default": 0 }, "statusDescription": { "type": "string", "example": "Bad Request - countryCode is missing" }, "beepTransactionID": { "type": "integer", "example": -1, "default": 0 }, "invoiceNumber": { "type": "string", "example": "" }, "payerTransactionID": { "type": "string", "example": "ec99b106-6cb7-4394-a510-1f53597a6a17" } } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "examples": { "Forbidden": { "value": "{\n \"authStatus\":{\n \"authStatusCode\":174,\n \"authStatusDescription\":\"Request Not permitted\"\n },\n \"results\":[\n {\n \"statusCode\":174,\n \"statusDescription\":\"Request Not permitted\",\n \"beepTransactionID\":-1,\n \"invoiceNumber\":\"\",\n \"payerTransactionID\":\"ec99b106-6cb7-4394-a510-1f53597a6a17\"\n }\n ]\n}" } }, "schema": { "type": "object", "properties": { "authStatus": { "type": "object", "properties": { "authStatusCode": { "type": "integer", "example": 174, "default": 0 }, "authStatusDescription": { "type": "string", "example": "Request Not permitted" } } }, "results": { "type": "array", "items": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 174, "default": 0 }, "statusDescription": { "type": "string", "example": "Request Not permitted" }, "beepTransactionID": { "type": "integer", "example": -1, "default": 0 }, "invoiceNumber": { "type": "string", "example": "" }, "payerTransactionID": { "type": "string", "example": "ec99b106-6cb7-4394-a510-1f53597a6a17" } } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "examples": { "Not Found": { "value": "{\n \"authStatus\":{\n \"authStatusCode\":174,\n \"authStatusDescription\":\"/payment Resource not found\"\n },\n \"results\":[\n {\n \"statusCode\":174,\n \"statusDescription\":\"/payment Resource not found\",\n \"beepTransactionID\":-1,\n \"invoiceNumber\":\"\",\n \"payerTransactionID\":\"ec99b106-6cb7-4394-a510-1f53597a6a17\"\n }\n ]\n}" } }, "schema": { "type": "object", "properties": { "authStatus": { "type": "object", "properties": { "authStatusCode": { "type": "integer", "example": 174, "default": 0 }, "authStatusDescription": { "type": "string", "example": "/payment Resource not found" } } }, "results": { "type": "array", "items": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 174, "default": 0 }, "statusDescription": { "type": "string", "example": "/payment Resource not found" }, "beepTransactionID": { "type": "integer", "example": -1, "default": 0 }, "invoiceNumber": { "type": "string", "example": "" }, "payerTransactionID": { "type": "string", "example": "ec99b106-6cb7-4394-a510-1f53597a6a17" } } } } } } } } } }, "deprecated": false } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ```