Account balance

Check whether Taura recognises a recipient's number and read the account's current monetary and voice balances. The check is read-only. It does not send a top-up, hold or spend wallet UNITS, or change any top-up.

What this is not

You want	Use
The UNITS available in your vendor wallet	GET /wallet/balance
Whether a top-up you sent was delivered	The top-up's status from Top-ups
A recipient's Taura account balance	POST /taura/accounts/balance (this page)

A recipient's balance is not proof that an earlier top-up was delivered or failed. A balance can change for reasons unrelated to your top-up, so never use it to decide whether to resend one. Read the top-up status instead.

POST/api/v1/taura/accounts/balance

Runs a fresh check with Taura on every call. Results are not cached.

Authentication

Use the same Bearer token as the other endpoints. Tokens created under Profile & API Keys carry the vendor ability this endpoint requires, so no new token or ability is needed. The account must be an enabled vendor. There is no anonymous access.

The recipient is sent in the JSON body, so it never appears in a URL or query string.

Request body

Field	Type	Required	Notes
recipient	string	Yes	Phone number in E.164 format, such as +263771000000. Spaces are removed. Validated the same way as POST /taura/topups. Maximum 16 characters.

No ref or units field is needed.

Example request

curl --request POST "https://taura.xashpay.com/api/v1/taura/accounts/balance" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer TOKEN" \
  --data '{ "recipient": "+263771000000" }'

Response: 200

Taura recognises the account:

{
  "account_check": {
    "outcome": "exists",
    "recipient": "+263771000000",
    "monetary_balance": "1.65",
    "voice_minutes": "0.00",
    "checked_at": "2026-10-20T14:02:32+00:00"
  }
}

Field	Type	Notes
outcome	string	exists on success.
recipient	string	The normalised number that was checked.
monetary_balance	string	Decimal string as reported by Taura, currently two decimal places. Taura's currency for this amount is not confirmed yet, so no currency code is returned. It is not UNITS.
voice_minutes	string	Voice balance in minutes, as a decimal string.
checked_at	string	ISO 8601 time of this check.

A zero balance ("0.00") is a valid, recognised account. It does not mean the account is missing.

Errors

Every unsuccessful response uses the same envelope: a message, a machine-readable code, and an account_check with outcome: "unavailable" and null balances. recipient and checked_at are filled in only when a check was attempted with Taura.

{
  "message": "Taura could not confirm this account right now. Try again later.",
  "code": "provider_timeout",
  "account_check": {
    "outcome": "unavailable",
    "recipient": "+263771000000",
    "monetary_balance": null,
    "voice_minutes": null,
    "checked_at": "2026-10-20T14:02:40+00:00"
  }
}

Status	code	Meaning	What to do
401	unauthenticated	Missing, invalid or revoked token.	Check the token.
403	forbidden	The account is disabled, is not a vendor, or the token lacks the vendor ability.	Contact Xash support.
422	invalid_recipient	recipient is missing or not a valid phone number. errors.recipient has the detail.	Correct the number.
429	rate_limited	Your account sent too many balance checks.	Wait for Retry-After, then try again.
503	lookup_busy	Balance checks across all vendors reached Taura's request limit. Taura was not contacted.	Wait for Retry-After, then try again.
503	provider_timeout	Taura did not answer in time.	Try again later.
503	provider_rate_limited	Taura is limiting requests.	Try again later.
503	provider_unavailable	Taura returned an error.	Try again later.
503	provider_response_unrecognised	Taura answered in a format this API does not recognise.	Try again later. Contact Xash support if it continues.
500	server_error	The check could not be completed.	Try again later.

An unavailable outcome means the account could not be confirmed. It does not mean the account is missing. Taura has not yet confirmed what it returns for an unknown number, so this API never reports a missing account. When that is confirmed, a separate outcome and status will be documented here.

Error responses never include Taura's raw response, its URL, or internal error details.

Rate limits

• Each vendor account can make up to 60 balance checks per minute. This limit is separate from the top-up limit.
• All vendors together share a limit on checks sent to Taura (120 per minute by default). Over it, the API answers 503 with lookup_busy and does not contact Taura.

Both limits are set by Xash and may change. Always honour Retry-After.

Privacy

Each check is recorded against your account for audit. Records are never linked to a top-up and never shown to other vendors.