> For the complete documentation index, see [llms.txt](https://apc-pay.gitbook.io/apc-pay-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apc-pay.gitbook.io/apc-pay-docs/apc-pay/balance-and-currency.md).

# Balance and Currency

Updated 2026-10-14

Call the balance and currency endpoints before creating a payout to confirm available funds, supported currency, amount precision, current rates and fees, and transaction limits.

## Authentication prerequisite

Both endpoints require the common `mchNo`, `appId`, `reqTime`, `nonceStr`, and `sign` request fields. Generate a fresh timestamp and nonce for each call, then sign the request using the endpoint's backend path.

Complete [Authentication and Request Signing](broken://pages/09fdb741f99cf1deb38cf1b90b063767f12807df) before using these examples.

## Query balance

```http
POST /balance/query
Content-Type: application/json; charset=utf-8
```

Send the request to:

```
https://pwc-pay-api.chiachair.com/v1/balance/query
```

Sign it using the backend path `/balance/query`. No operation-specific business fields are required.

### Request example

The signature is a placeholder. Generate a new timestamp, nonce, and signature for every call.

```json
{
  "mchNo": "your-merchant-number",
  "appId": "your-app-id",
  "reqTime": "2026-10-14T08:20:00.000Z",
  "nonceStr": "0123456789abcdef0123456789abcdef",
  "sign": "base64-rsa-sha256-signature"
}
```

### Response data

| Field      | Description                                  |
| ---------- | -------------------------------------------- |
| `usable`   | USDT available to fund new payouts.          |
| `locked`   | USDT reserved by active payout orders.       |
| `total`    | Total merchant USDT balance.                 |
| `nonceStr` | Request nonce returned for response binding. |

For a successful non-empty response, verify the platform signature over `data` and require the response nonce to match the request before using any balance value.

## Query currency configuration

```http
POST /currency/query
Content-Type: application/json; charset=utf-8
```

Send the request to:

```
https://pwc-pay-api.chiachair.com/v1/currency/query
```

Sign it using the backend path `/currency/query`.

Send `fiatCurrency` to retrieve one ISO 4217 currency. Omit it to retrieve all currencies enabled for the app.

### Request example

```json
{
  "mchNo": "your-merchant-number",
  "appId": "your-app-id",
  "reqTime": "2026-10-14T08:25:00.000Z",
  "nonceStr": "fedcba9876543210fedcba9876543210",
  "fiatCurrency": "PHP",
  "sign": "base64-rsa-sha256-signature"
}
```

### Currency response fields

Each returned currency object includes:

| Field                  | Description                                       |
| ---------------------- | ------------------------------------------------- |
| `currency`             | ISO 4217 currency code.                           |
| `decimals`             | Exact decimal places required for payout amounts. |
| `exchangeRate`         | Market rate in fiat per USDT.                     |
| `feeRate`              | Merchant percentage fee configuration.            |
| `fixedFee`             | Merchant fixed-fee configuration.                 |
| `adjustedExchangeRate` | `exchangeRate / (1 + feeRate)`.                   |
| `minAmount`            | Minimum allowed fiat amount per payout.           |
| `maxAmount`            | Maximum allowed fiat amount per payout.           |
| `rateUpdatedAt`        | UTC timestamp for the displayed rate.             |

Verify the platform signature and response nonce before using these values.

> 📌
>
> ### Exact amount precision
>
> Format `fiatAmount` as a decimal string using exactly the returned `decimals`. Do not use binary floating-point values for money.

## Calculate the estimated USDT cost

APC Pay calculates the locked USDT cost using:

```
adjustedExchangeRate = exchangeRate / (1 + feeRate)
usdtAmount = fiatAmount / adjustedExchangeRate + fixedFee / exchangeRate
```

The result is rounded up to 18 USDT decimal places. The platform locks rates and fees when the payout order is created, so your pre-payout calculation is an estimate until create succeeds.

## Pre-payout validation

Before calling `/payout/create`:

1. Confirm the requested currency appears in the app's currency response.
2. Format the amount with exactly `decimals` decimal places.
3. Require `minAmount <= fiatAmount <= maxAmount`.
4. Confirm the QR payload's amount and currency agree with the request.
5. Calculate the estimated `usdtAmount` with decimal arithmetic and round up as documented.
6. Confirm `usable` balance is sufficient.
7. Refresh stale currency data according to your operational policy before submitting the order.

APC Pay remains the source of truth for the values locked in the successful create response.

## Related errors

|   Code | Meaning                  | Action                                                       |
| -----: | ------------------------ | ------------------------------------------------------------ |
| `3001` | `INSUFFICIENT_BALANCE`   | Fund the merchant wallet, then retry the same payout safely. |
| `3003` | `CURRENCY_NOT_SUPPORTED` | Enable the currency or choose an enabled one.                |
| `3004` | `RATE_UNAVAILABLE`       | Retry later with a fresh time, nonce, and signature.         |
| `3010` | `AMOUNT_OUT_OF_RANGE`    | Refresh the limits and correct the amount.                   |

See [Payout Statuses and Errors](broken://pages/1701152330ec298b264aa8660498f37921c96df6) for the complete error table and retry guidance.

## Next step

Continue to [Create a Payout](broken://pages/85bb23f0c564b16167e4d27ad120123daf5f90b3).