Armada Armada API v2

Wallet

Armada charges deliveryFee per completed delivery. Merchants pay via a prepaid wallet — top it up, and every successful delivery draws from it. This page covers the read endpoint, when the balance moves, and how to react when it runs low.

How the balance moves

  • Delivery completed → balance is debited by the order's deliveryFee (shown on the order at create time, not re-computed).
  • Delivery canceled (any status other than completed) → no charge.
  • Delivery failed → no charge.
  • Top-up → balance credited, an invoice with type: TOPUP_WALLET is generated (see Invoices).
  • Refund / adjustment → balance credited, corresponding REFUND_WALLET invoice generated.
GET /v2/wallet

Get wallet balance

Returns the current balance, currency, and low-balance threshold.

Permission: wallet:read.

GET /v2/wallet 
curl -sS https://api.armadadelivery.com/v2/wallet \
  -H "Authorization: Key $ARMADA_API_KEY" \
  -H "x-armada-timestamp: $TS" \
  -H "x-armada-signature: $SIG"

Response

Field
Type
Description
balance required
number
Current balance in the merchant's currency. Positive for credit, zero when empty. Can go negative on postpaid terms.
currency required
string
ISO-4217 code. Kuwait merchants are KWD, Saudi SAR, Bahrain BHD.
warningBalanceLevel optional
number | null
The threshold at which the wallet.balance_low webhook fires. Configured per merchant; null if low-balance alerts are off.

Low-balance webhook

Polling GET /v2/wallet in a loop is wasteful — configure a webhook once and Armada pushes you a notice when the balance drops below warningBalanceLevel.

  • Topic: wallet.balance_low
  • Configured in the API Keys page (Wallet low balance webhook block) per API key.
  • Fires once when balance crosses the threshold going down. Does not fire on every transaction below the threshold — that would be too noisy. Triggers again only after balance crosses back above and then below again.

See Webhooks → wallet.balance_low for the payload shape.

Topping up

Top-ups happen through the business-app Wallet page — the v2 API doesn't expose top-up endpoints to merchants directly. You'll see the resulting invoice through GET /v2/invoices with status=topup.

← Branches Invoices →