Simulate Wallet Funding
Credit your workspace wallet with a simulated bank deposit. This endpoint is only available in the Sandbox environment. Use it during integration testing to add funds without a real bank transfer.
Endpoint
/v1/wallet/simulateRequired permission: wallet:fund:simulate
Calling this endpoint in the Production environment returns a 403 Forbidden error. It is strictly for Sandbox use.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
amount | Integer | ✅ | Amount to deposit in ₦. Must be greater than zero. |
paymentMethod | String | ✅ | Simulated payment route (e.g. "Bank Transfer", "Card"). Used for display purposes only. |
bankName | String | ✅ | Name of the simulated bank (e.g. "GTBank"). Appears in the transaction description. |
bankReference | String | ✅ | A simulated transaction reference from the bank (e.g. "FBN2026070100123"). Stored on the ledger entry. |
Response
On success, returns the created transaction entry. Your wallet balance is updated atomically.
| Field | Type | Description |
|---|---|---|
id | String | Unique ledger transaction ID (e.g. TNX_A1B2C3D4). |
date | String | ISO 8601 UTC timestamp of when the deposit was processed. |
type | String | Always TOPUP for this endpoint. |
description | String | Auto-generated description (e.g. "Prepaid Deposit via GTBank"). |
amount | Integer | Credited amount in ₦. |
balanceAfter | Integer | Wallet balance after this transaction. |
reference | String | The bankReference you provided. |
What Happens Under the Hood
The deposit and wallet balance update are committed atomically using a DynamoDB transaction. If the balance was already updated by another process between the read and write, the operation retries automatically to prevent double-credits.
Dispatching a wallet.funded webhook event to your registered endpoint is also triggered on success.
{
"amount": 50000,
"paymentMethod": "Bank Transfer",
"bankName": "GTBank",
"bankReference": "GTB2026070100987"
}