# 💸Balance API

#### Endpoint

**POST**\
`https://malum.co/api/v3/account/balance`

#### Headers

To authenticate your request, use the following header structure:

```css
MALUM: {Business ID}:{Secret Key}
```

* **Business ID**: Your Malum account’s unique identifier.
* **Secret Key**: Your API secret key for secure access.

#### Response Format

**Success Response**

When the request is successful, the API will return the following JSON structure:

```json
{
    "status": "success",
    "message": "Balance retrieved.",
    "data": {
        "balance": "10,000.00",
        "pending": "0.00",
        "currency": "USD"
    },
    "timestamp": 1728676259
}
```

* **status**: Message indicating the successful retrieval of the balance.
* **message**: HTTP status code (200 indicates success).
* **data**:
  * **balance**: The available balance in your account.
  * **pending**: Amount pending from any incomplete transactions.
  * **currency**: The currency of the account balance (e.g., USD).
* **timestamp**: Unix timestamp of when the balance was retrieved.

**Error Response**

If the request fails (e.g., invalid API key), the API will return an error in the following format:

```json
{
    "status": "failed",
    "error": "Invalid API Key.",
    "timestamp": 1728676669
}
```

* **status**: Error status message indicating failure.
* **error**: A descriptive error message explaining the issue.
* **timestamp**: Unix timestamp when the error occurred.

#### Example Request

```bash
curl --location --request POST 'https://malum.co/api/v3/account/balance' \
--header 'MALUM: BusinessID:SecretKey'
```

#### Example Success Response

```json
{
    "status": "Balance retrieved.",
    "message": 200,
    "data": {
        "balance": "10,000.00",
        "pending": "0.00",
        "currency": "USD"
    },
    "timestamp": 1728676259
}
```

#### Example Error Response

<pre class="language-json"><code class="lang-json">{
<strong>    "status": "failed",
</strong>    "error": "Invalid API Key.",
    "timestamp": 1728676669
}
</code></pre>

#### Notes

* Ensure that your **Business ID** and **Secret Key** are correct and up-to-date.
* API responses are in JSON format and include a Unix timestamp for logging purposes.