Currencies

Every PesaVoucher user has a preferred currency — the currency their wallet balance is kept in. When a deposit comes in a different currency (a customer paying via PayPal in USD, or you collecting via Pesapal/Paystack in whatever currency was available at checkout), PesaVoucher converts it automatically before crediting the wallet. You never need to convert currency yourself.

The "rail" is just the local settlement network for that currency — it doesn't limit how a customer can pay. A player whose PesaVoucher account is TZS can pay through any supported gateway in any currency it offers; PesaVoucher converts into TZS before crediting them.

Example — Linebet. Say Linebet has a player in Dar es Salaam whose PesaVoucher wallet is TZS. Linebet's checkout collects the deposit via Pesapal, which on that player's device only offered card payment in KES. Linebet's backend calls PesaVoucher's deposit endpoint with amount: 5000, currency: "KES". PesaVoucher:

1. Confirms the KES payment came through
2. Converts 5000 KES into TZS at the current rate
3. Credits the player's wallet in TZS — not KES
4. Returns both figures, so Linebet can show the player what they were actually credited

{
  "success": true,
  "amount": 175438.60,
  "currency": "TZS",
  "amount_display": "TSh 175,438.60",
  "charged_amount": 5000,
  "charged_currency": "KES"
}

charged_amount/charged_currency only appear when a conversion actually happened. If you deposit in the same currency as the player's wallet, the response is just amount/currency as normal.

This works the same way whether the deposit came from your backend (e.g. after collecting via Pesapal, PayPal, or Paystack) or directly from the customer (e.g. paying via PayPal at checkout) — either way, PesaVoucher looks up that specific player's preferred currency and converts into it.

Rates are applied at the moment of crediting, not when the deposit started. If you need the exact rate used for a transaction, check the transaction record or your webhook payload.

Some rails are tied to one currency by nature — M-Pesa STK Push, for example, only ever moves KES. If a player's wallet is in a currency M-Pesa can't settle, or a currency PesaVoucher doesn't yet support, the request is rejected rather than guessed at:

{
  "success": false,
  "message": "Could not convert USD to this user's account currency (XOF): Currency not found or inactive"
}

HTTP Status: 400

If you're onboarding players in a currency you don't see in the table above, contact support@pesavoucher.com before going live — it's a quick addition on our side, but it needs to exist before deposits in it will convert correctly.

• Read currency/amount back from the response — don't assume it matches what you sent
• If charged_amount/charged_currency are present, a conversion happened — show the player the credited amount/currency, not the charged figures
• Handle the 400 conversion error distinctly from other validation errors so you can surface a clear message
• Don't convert currency on your own side — PesaVoucher's rate at credit time is the source of truth