> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rolla.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Simulate an Account Deposit (Sandbox)
> Sandbox only. Simulates an incoming USD deposit into one of an account's deposit accounts, so you can exercise deposit crediting and webhooks without a real transfer.
With `bank_account_reference` the deposit is credited to that specific account; without it, to the client's primary account. The balance is credited **asynchronously** via the provider's normal deposit webhook — this call only submits the simulated inbound transfer.
This endpoint does not exist in production; calls there return `404`.
A testing helper that simulates an **incoming USD deposit** into one of an account's deposit accounts, so you can verify crediting and webhooks end-to-end **without sending a real wire transfer**.
Its purpose is to let you prove **attribution**: when a client holds several deposit accounts — one per [`reference`](/api-reference/endpoint/accounts/issue-bank-account#multiple-usd-deposit-accounts) — you can send a deposit to one of them and confirm it lands against that reference and no other.
**Sandbox / testing only.** This endpoint does **not** exist in production — calls to the production API return `404 Not Found`.
## Prerequisites
The account must already have an **issued, active USD account**. Issue one via [Issue a Bank Account](/api-reference/endpoint/accounts/issue-bank-account) with `currency: "USD"`. If none is provisioned, the call returns `404` with code `USD_ACCOUNT_NOT_FOUND`.
## Request Body
| Field | Type | Required | Description |
| ------------------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `amount` | string | Yes | Deposit amount in major units of USD (e.g. `"100"` or `"100.50"`). Must be greater than 0. |
| `bank_account_reference` | string | No | Which of the client's deposit accounts to credit, as passed to Issue Bank Account. Omit to credit the **primary** account. |
| `reference` | string | No | Your own reference carried on the simulated transfer itself. Generated when omitted. |
| `sender_name` | string | No | Name recorded as the sender on the resulting transaction. |
The two references do different jobs. `bank_account_reference` chooses **which account receives the money**; `reference` is a label on **the transfer**.
## Example Request
Credit the deposit account issued for `store-amazon-uk`:
```bash theme={null}
curl -X POST "https://api-staging.rolla.xyz/api/v1/external/accounts/eec3cbed-79d8-4370-87a0-b6be9e287337/bank-accounts/simulate-deposit" \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"amount": "250.00",
"bank_account_reference": "store-amazon-uk",
"sender_name": "Amazon EU S.a.r.l."
}'
```
## Example Response
```json theme={null}
{
"status": 201,
"success": true,
"message": "Simulated USD deposit submitted",
"data": {
"status": "submitted",
"amount": "250.00",
"currency": "USD",
"reference": "RL_SIM_C029D665B02F",
"bankAccountReference": "store-amazon-uk",
"transferId": "5b3c2fa0-d4db-49d5-9484-0af9aec2b155",
"message": "Simulated incoming USD transfer submitted. The balance will be credited to the wallet via the provider webhook."
}
}
```
`bankAccountReference` echoes which account was credited — `null` when the primary was.
## What happens
1. The request is routed to the USD provider's sandbox, which submits a simulated incoming transfer against the deposit account you named. The response `status` is `submitted` — the balance is **not** credited yet.
2. The provider then delivers a deposit webhook through the **same crediting path a real deposit uses**, and the wallet is credited.
3. The transaction completes, emitting a `transaction.pending` event followed by `transaction.completed`. See [Webhook Payloads](/api-reference/webhooks/payloads).
Because the credit arrives via the provider webhook, it is **not instant**. After a `submitted` response, poll [List Wallets](/api-reference/endpoint/wallet/wallets) or [Transactions](/api-reference/endpoint/wallet/transactions) until the balance lands.
## Unknown references
A `bank_account_reference` with no account behind it returns `404` naming the reference, rather than quietly falling back to the primary account — so a typo in a test cannot credit the wrong balance and leave you reading the result as a pass:
```json theme={null}
{
"status": 404,
"message": "No deposit account exists for reference \"store-does-not-exist\". Issue one with that reference first."
}
```
To simulate a deposit into **your own** business's wallet rather than one of your accounts', use [Simulate a USD Deposit](/api-reference/endpoint/wallet/simulate-usd-deposit). That endpoint always credits the primary account and cannot target a `reference`.
## OpenAPI
````yaml POST /accounts/{accountId}/bank-accounts/simulate-deposit
openapi: 3.1.0
info:
title: Rolla Developer API
description: >-
API for programmatic transaction management on the Rolla platform. Monetary
`amount` fields use the smallest unit of the referenced currency unless an
endpoint says otherwise (e.g. NGN = kobo, USD = cents, where **100 cents =
USD 1.00**).
version: 1.0.0
servers:
- url: https://api.rolla.xyz/api/v1/external
description: Production server
security:
- apiKeyAuth: []
paths:
/accounts/{accountId}/bank-accounts/simulate-deposit:
post:
summary: Simulate a Deposit (Sandbox)
description: >-
Sandbox only. Simulates an incoming USD deposit into one of an account's
deposit accounts, so you can exercise deposit crediting and webhooks
without a real transfer.
With `bank_account_reference` the deposit is credited to that specific
account; without it, to the client's primary account. The balance is
credited **asynchronously** via the provider's normal deposit webhook —
this call only submits the simulated inbound transfer.
This endpoint does not exist in production; calls there return `404`.
operationId: simulateAccountDeposit
parameters:
- name: accountId
in: path
required: true
description: >-
Identifier of an account owned by the same user as your API key's
business
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SimulateAccountDepositRequest'
responses:
'201':
description: Simulated deposit submitted
content:
application/json:
schema:
$ref: '#/components/schemas/SimulateAccountDepositResponse'
'400':
description: Invalid request body
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: >-
Account not found, no USD account provisioned, or no account exists
for the given `bank_account_reference`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
SimulateAccountDepositRequest:
type: object
required:
- amount
properties:
amount:
type: string
description: >-
Deposit amount in major units of USD, e.g. "100" or "100.50". Must
be greater than 0.
example: '250.00'
bank_account_reference:
type: string
maxLength: 100
description: >-
Which of the account's deposit accounts to credit, as passed to
Issue Bank Account. Omit to credit the client's primary account. A
reference with no account behind it returns `404` rather than
falling back to the primary.
example: store-amazon-uk
reference:
type: string
maxLength: 120
description: >-
Your own reference carried on the simulated transfer itself.
Generated when omitted.
sender_name:
type: string
maxLength: 120
description: Name recorded as the sender on the resulting transaction.
example: Amazon EU S.a.r.l.
SimulateAccountDepositResponse:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: Simulated USD deposit submitted
data:
type: object
properties:
status:
type: string
example: submitted
amount:
type: string
example: '250.00'
currency:
type: string
example: USD
reference:
type: string
description: Reference on the simulated transfer.
example: RL_SIM_C029D665B02F
bankAccountReference:
type: string
nullable: true
description: >-
Which deposit account was credited; `null` for the client's
primary.
example: store-amazon-uk
transferId:
type: string
nullable: true
message:
type: string
Error:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Your Rolla API key
````