Skip to main content
POST
Simulate a Deposit (Sandbox)
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 — 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 with currency: "USD". If none is provisioned, the call returns 404:

Request Body

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:

Example Response

bankAccountReference echoes which account was credited — null when the primary was. paymentRail echoes the rail the deposit will arrive on. transferId is the provider’s id for the simulated transfer and is null when the provider sandbox does not return one. Malformed bodies (for example a non-numeric amount) return 400 with "message": "Validation failed" and an errors array; a rejection from the provider sandbox returns 400 with its message.

Choosing the rail

Pass payment_rail to test how you reconcile each channel. The resulting deposit reports it as payment_rail on the webhook and the transactions API, and is charged that rail’s pay-in fee, exactly as a real deposit would be: Any other value returns 400.
The deposit’s pay-in fee is taken from the amount before it is credited, so simulate an amount larger than the fee for the rail you choose. A deposit that the fee would swallow is not credited.

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, each carrying payer.name (your sender_name, or "Sandbox Sender") and payment_rail. See Webhook Payloads.
If Rolla cannot record the simulation’s sender and rail, the request fails with an error and no transfer is submitted, so it is safe to retry. A submitted response always produces a deposit carrying them.
Because the credit arrives via the provider webhook, it is not instant. After a submitted response, poll List Wallets or 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:
To simulate a deposit into your own business’s wallet rather than one of your accounts’, use Simulate a USD Deposit. That endpoint always credits the primary account and cannot target a reference.

Authorizations

X-API-Key
string
header
required

Your Rolla API key

Path Parameters

accountId
string<uuid>
required

Identifier of an account owned by the same user as your API key's business

Example:

"eec3cbed-79d8-4370-87a0-b6be9e287337"

Body

application/json
amount
string
required

Deposit amount in major units of USD, e.g. "100" or "100.50". Must be greater than 0.

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

"250.00"

bank_account_reference
string

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.

Required string length: 1 - 100
Example:

"store-amazon-uk"

reference
string

Your own reference carried on the simulated transfer itself. Generated when omitted.

Required string length: 1 - 120
sender_name
string

Name recorded as the sender on the resulting transaction. Returned as payer.name. Defaults to "Sandbox Sender" when omitted.

Required string length: 1 - 120
Example:

"Amazon EU S.a.r.l."

payment_rail
enum<string>
default:ach

Sandbox only. Rail the simulated deposit arrives on. Reported on the deposit's payment_rail as ach, wire_domestic (for fedwire) or wire_international (for swift), and charged that rail's pay-in fee.

Available options:
ach,
fedwire,
swift
Example:

"swift"

Response

Simulated deposit submitted

status
integer
required
Example:

201

message
string
required
Example:

"Simulated USD deposit submitted"

success
boolean
required
Example:

true

data
object
required