Simulate Deposit (Sandbox Only)

Simulate a deposit to a virtual account for testing purposes. This endpoint is only available in sandbox mode and allows you to credit test funds to your virtual accounts so you can test transfers and other functionalities.

Note: This endpoint only works with test API keys (esca_test_*). Attempting to use it with a live API key will result in a 403 Forbidden error.

POST /v1/virtual-account/simulate-deposit

Header	Required	Description
`X-Api-Key`	Yes	Your test API key (must start with `esca_test_`)
`Content-Type`	Yes	`application/json`

Request Body

Field	Type	Required	Description
`accountId`	integer	Yes	Virtual account ID to credit
`amount`	number	Yes	Amount to deposit (min: 100, max: 10,000,000)
`narration`	string	No	Description for the deposit

Example Request

curl -X POST "https://sandbox.api.esca.finance/v1/virtual-account/simulate-deposit" \
  -H "X-Api-Key: esca_test_your_test_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": 12345,
    "amount": 100000,
    "narration": "Test deposit for integration testing"
  }'

Example Response

{
  "status": true,
  "data": {
    "accountId": 12345,
    "accountNumber": "8012345678",
    "accountName": "ESCA/John Doe",
    "amount": 100000,
    "currency": "NGN",
    "narration": "Test deposit for integration testing",
    "balance": 100000,
    "creditedAt": "2026-01-18T10:30:00.000Z"
  }
}

Response Fields

Field	Type	Description
`accountId`	integer	The credited account ID
`accountNumber`	string	Virtual account number
`accountName`	string	Name on the account
`amount`	number	Amount deposited
`currency`	string	Account currency
`narration`	string	Deposit description
`balance`	number	New account balance after deposit
`creditedAt`	string	Timestamp of the deposit (ISO 8601)

Error Responses

Status	Description
`400 Bad Request`	Invalid parameters (amount out of range, missing fields)
`403 Forbidden`	Endpoint called with a live API key instead of test key
`404 Not Found`	Virtual account not found or doesn't belong to your business

Webhook

When a simulated deposit is processed, a virtual_account.credited webhook event will be dispatched.

{
  "event": "virtual_account.credited",
  "data": {
    "accountId": 12345,
    "accountNumber": "8012345678",
    "accountName": "ESCA/John Doe",
    "amount": 100000,
    "currency": "NGN",
    "narration": "Test deposit for integration testing",
    "sender": "Sandbox Simulation",
    "senderAccountNumber": "0000000000",
    "balance": 100000,
    "creditedAt": "2026-01-18T10:30:00.000Z"
  }
}