Wallet
Merchant Balances
Retrieve available, pending, and total balances for all currencies in your merchant wallet. Use this before disbursements to verify you have sufficient funds.
cURL
curl -X GET \ https://pay.digitalservicescenter.rw/generation/v2/balance \ -H "X-DGS-API-Key: YOUR_API_KEY"
JSON
{
"status": "success",
"error_code": "00",
"merchant_id": "merchant_uuid",
"balances": [
{
"currency": "USD",
"pending_balance": 50.00,
"available_balance": 200.00,
"total_balance": 250.00
},
{
"currency": "RWF",
"pending_balance": 1000.00,
"available_balance": 5000.00,
"total_balance": 6000.00
}
]
}
| Field | Description |
|---|---|
pending_balance | Funds received but not yet settled (e.g. in processing). |
available_balance | Funds immediately available for disbursement or withdrawal. |
total_balance | Sum of pending and available — your total wallet value. |
Wallet
Currency Conversion
Convert funds between currencies within your merchant wallet. Use action: "preview" to see the expected conversion amount and rate without moving any money, then call again with action: "convert" to execute.
| Field | Type | Description |
|---|---|---|
action | string | "preview" — read-only rate check. "convert" — execute and move funds. |
from_currency | string | Source currency (e.g. USD). |
to_currency | string | Target currency (e.g. EUR). |
from_amount | number | Amount in from_currency to convert. Must be > 0. |
JSON — Preview response (no funds moved)
{
"status": "success",
"message": "Conversion preview — no funds moved",
"from_currency": "USD",
"from_amount": 100,
"to_currency": "EUR",
"to_amount": 94.50,
"rate": 0.945000,
"rate_display": "1 USD = 0.9450 EUR",
"fee": 0
}
JSON — Execution response (funds debited, credit pending)
{
"status": "success",
"message": "Conversion initiated. EUR balance will be credited shortly.",
"dgs_conversion_ref": "DGSCONV1A2B3C4D",
"conversion_status": "processing",
"from_currency": "USD",
"from_amount": 100,
"to_currency": "EUR",
"to_amount": 94.50,
"rate": 0.945000,
"fee": 0
}
JSON — Insufficient balance error
{
"status": "failed",
"message": "Insufficient USD balance",
"error_code": "VALIDATION_ERROR",
"available_balance": 50,
"required": 100,
"currency": "USD"
}
Notes
- Conversion is currently fee-free.
- Live exchange rates are applied at execution time — rates shown in preview may shift slightly.
- If the provider rejects the transfer, the source currency balance is automatically refunded.
- Track conversions using
dgs_conversion_ref.
Wallet
Conversion Webhook
Sent automatically when a currency conversion changes status. Use this to update your records and reconcile wallet balances.
JSON — Webhook Payload
{
"event": "conversion.success",
"dgs_reference": "DGSCONV1A2B3C4D",
"status": "success",
"from_currency": "USD",
"from_amount": 100,
"to_currency": "EUR",
"to_amount": 94.50,
"rate": 0.945,
"rate_display": "1 USD = 0.9450 EUR"
}
JSON — Webhook Payload
{
"event": "conversion.failed",
"dgs_reference": "DGSCONV1A2B3C4D",
"status": "failed",
"from_currency": "USD",
"from_amount": 100,
"to_currency": "EUR",
"fail_reason": "Insufficient balance",
"refund_amount": 100,
"refund_currency": "USD"
}