Skip to main content
POST
Simulate a Deposit (Sandbox)
A testing helper that injects a deposit into one of your own virtual accounts so you can verify your integration end-to-end — the wallet is credited and the deposit webhook is delivered — without sending a real bank transfer. Use it while building your deposit flow: create a customer virtual account, simulate a deposit into it, and confirm your endpoint receives the transaction.completed webhook and attributes it to the right end-user.
Sandbox / testing only. This endpoint does not exist in production — calls to the production API return 404 Not Found. Use it against your sandbox environment only.

Targeting an account

Send exactly one of the following. The account must belong to your business.
  • customer_identifier — the id you used when creating a customer virtual account. Best when testing per-end-user deposits.
  • account_number — the number of any of your virtual accounts (static, dynamic, or customer).

Request Body

Example Request — by customer_identifier

Example Request — by account_number

Example Response

customer_identifier is echoed only when you targeted the account that way; a request by account_number omits it. status is the transaction’s own status, completed once the deposit has been posted. An account number or customer identifier that does not match an active virtual account of yours returns 404, rather than crediting anything:
A body that fails validation, such as neither or both targeting fields or a non-numeric amount, returns 400 with "message": "Validation failed" and an errors array.

What happens

  1. The deposit is routed through the same crediting path a real provider deposit uses — your wallet is credited (net of the pay-in fee) and the deposit is tagged with the account’s provider.
  2. The transaction is completed, emitting the deposit webhook to your configured endpoint: a transaction.pending event, followed by transaction.completed.
  3. For a customer virtual account, the webhook payload includes the customer_identifier, so you can attribute the deposit to the right end-user. See Webhook Payloads.
amount must be greater than the pay-in fee on the account. A smaller amount is rejected with 400 and the message Deposit amount is too small — it must be greater than the payin fee configured on this account. Try a larger amount.
Because this credits a real (sandbox) wallet balance, treat it like any other write: it moves your test wallet’s balance and generates a real transaction record and webhook delivery.

Authorizations

X-API-Key
string
header
required

Your Rolla API key

Body

application/json
amount
string
required

Deposit amount in major units of the account currency (e.g. Naira). Must be greater than the pay-in fee on the account.

Pattern: ^\d+(\.\d{1,2})?$
Example:

"2000"

customer_identifier
string

Customer id of one of your customer virtual accounts. Provide this or account_number, not both.

Required string length: 1 - 100
Example:

"user-12345"

account_number
string

Account number of any of your virtual accounts. Provide this or customer_identifier, not both.

Required string length: 1 - 50
Example:

"4382272943"

sender_name
string

Name to record as the sender on the transaction.

Required string length: 1 - 120
Example:

"John Sender"

provider
enum<string>

Force the provider tag on the deposit. Omit to inherit the target account's own provider.

Available options:
HABARI,
NOMBA,
VFD,
NETMFB

Response

Simulated deposit created

status
integer
required
Example:

201

message
string
required
Example:

"Simulated deposit created"

success
boolean
required
Example:

true

data
object
required