Get Balance

Use getBalance to retrieve your available company balance in a specific currency, along with the exchange rate applied to your account.

Common use: check funds before creating xPay allocations or bank/mobile payouts.

Endpoint

POST https://secure.3gdirectpay.com/API/v6/

Headers

Content-Type: application/xml; charset=utf-8
Accept: application/xml

Request

Required Fields

Field	Req	Description
`Request`	Yes	Must be `getBalance`
`CompanyToken`	Yes	Your merchant token
`Currency`	Yes	ISO currency code (e.g., `USD`, `KES`, `ZAR`)

Example Request (XML)

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <Request>getBalance</Request>
  <CompanyToken>YOUR_COMPANY_TOKEN</CompanyToken>
  <Currency>USD</Currency>
</API3G>

Response

Example Success Response (XML)

<?xml version="1.0" encoding="utf-8"?>
<API3G>
  <CompanyBalance>100,000</CompanyBalance>
  <ExchangeRate>1</ExchangeRate>
</API3G>

Field Reference

Field	Description
`CompanyBalance`	Your available balance in the requested currency (format may include thousand separators)
`ExchangeRate`	Account exchange rate used for this currency (string/decimal)

Notes & Best Practices

Request one currency at a time. Call again for additional currencies you support.
If you plan to executeXpay or other payouts, validate you have sufficient CompanyBalance first.
Treat the response as point-in-time; balances change with subsequent transactions.
For reporting, store (timestamp, currency, CompanyBalance, ExchangeRate).

Errors (typical)

While the source example only lists success, standard v6 behavior commonly includes:

Code	Meaning	Action
`801`	Missing `CompanyToken`	Include a valid token
`803`	Bad/missing `Request` name	Ensure `getBalance`
`804`	XML error	Check tag names/encoding
`902`	Data mismatch	Verify `Currency` is supported

Typical Usage with xPay

sequenceDiagram
  participant M as Merchant
  participant D as DPO API

  M->>D: getBalance (Currency)
  D-->>M: CompanyBalance + ExchangeRate
  M->>D: executeXpay (Allocations within balance)
  D-->>M: AllocationId(s) + RequestRef

Quick Links

Execute xPay (v6) → /developers/execute-xpay
Verify xPay (v6) → /developers/verify-xpay
Get Services (v6) → /developers/get-services