curl --request POST \
--url https://api-staging.rolla.xyz/api/v1/external/accounts/{accountId}/bank-accounts/simulate-deposit \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"amount": "250.00",
"bank_account_reference": "store-amazon-uk",
"sender_name": "Amazon EU S.a.r.l."
}
'import requests
url = "https://api-staging.rolla.xyz/api/v1/external/accounts/{accountId}/bank-accounts/simulate-deposit"
payload = {
"amount": "250.00",
"bank_account_reference": "store-amazon-uk",
"sender_name": "Amazon EU S.a.r.l."
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: '250.00',
bank_account_reference: 'store-amazon-uk',
sender_name: 'Amazon EU S.a.r.l.'
})
};
fetch('https://api-staging.rolla.xyz/api/v1/external/accounts/{accountId}/bank-accounts/simulate-deposit', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-staging.rolla.xyz/api/v1/external/accounts/{accountId}/bank-accounts/simulate-deposit",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => '250.00',
'bank_account_reference' => 'store-amazon-uk',
'sender_name' => 'Amazon EU S.a.r.l.'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-staging.rolla.xyz/api/v1/external/accounts/{accountId}/bank-accounts/simulate-deposit"
payload := strings.NewReader("{\n \"amount\": \"250.00\",\n \"bank_account_reference\": \"store-amazon-uk\",\n \"sender_name\": \"Amazon EU S.a.r.l.\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-staging.rolla.xyz/api/v1/external/accounts/{accountId}/bank-accounts/simulate-deposit")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": \"250.00\",\n \"bank_account_reference\": \"store-amazon-uk\",\n \"sender_name\": \"Amazon EU S.a.r.l.\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-staging.rolla.xyz/api/v1/external/accounts/{accountId}/bank-accounts/simulate-deposit")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": \"250.00\",\n \"bank_account_reference\": \"store-amazon-uk\",\n \"sender_name\": \"Amazon EU S.a.r.l.\"\n}"
response = http.request(request)
puts response.read_body{
"status": 201,
"message": "Simulated USD deposit submitted",
"success": true,
"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.",
"paymentRail": "swift"
}
}{
"status": 400,
"message": "Validation failed",
"code": "ACCOUNT_RESTRICTED",
"errors": [
{
"path": [
"amount"
],
"message": "amount must be a whole number of smallest currency units (e.g. cents)"
}
]
}{
"status": 400,
"message": "Validation failed",
"code": "ACCOUNT_RESTRICTED",
"errors": [
{
"path": [
"amount"
],
"message": "amount must be a whole number of smallest currency units (e.g. cents)"
}
]
}{
"status": 404,
"message": "No deposit account exists for reference \"store-does-not-exist\". Issue one with that reference first."
}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.
The route is not registered in production, where it returns 404.
curl --request POST \
--url https://api-staging.rolla.xyz/api/v1/external/accounts/{accountId}/bank-accounts/simulate-deposit \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"amount": "250.00",
"bank_account_reference": "store-amazon-uk",
"sender_name": "Amazon EU S.a.r.l."
}
'import requests
url = "https://api-staging.rolla.xyz/api/v1/external/accounts/{accountId}/bank-accounts/simulate-deposit"
payload = {
"amount": "250.00",
"bank_account_reference": "store-amazon-uk",
"sender_name": "Amazon EU S.a.r.l."
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: '250.00',
bank_account_reference: 'store-amazon-uk',
sender_name: 'Amazon EU S.a.r.l.'
})
};
fetch('https://api-staging.rolla.xyz/api/v1/external/accounts/{accountId}/bank-accounts/simulate-deposit', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-staging.rolla.xyz/api/v1/external/accounts/{accountId}/bank-accounts/simulate-deposit",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => '250.00',
'bank_account_reference' => 'store-amazon-uk',
'sender_name' => 'Amazon EU S.a.r.l.'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-staging.rolla.xyz/api/v1/external/accounts/{accountId}/bank-accounts/simulate-deposit"
payload := strings.NewReader("{\n \"amount\": \"250.00\",\n \"bank_account_reference\": \"store-amazon-uk\",\n \"sender_name\": \"Amazon EU S.a.r.l.\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-staging.rolla.xyz/api/v1/external/accounts/{accountId}/bank-accounts/simulate-deposit")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": \"250.00\",\n \"bank_account_reference\": \"store-amazon-uk\",\n \"sender_name\": \"Amazon EU S.a.r.l.\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-staging.rolla.xyz/api/v1/external/accounts/{accountId}/bank-accounts/simulate-deposit")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": \"250.00\",\n \"bank_account_reference\": \"store-amazon-uk\",\n \"sender_name\": \"Amazon EU S.a.r.l.\"\n}"
response = http.request(request)
puts response.read_body{
"status": 201,
"message": "Simulated USD deposit submitted",
"success": true,
"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.",
"paymentRail": "swift"
}
}{
"status": 400,
"message": "Validation failed",
"code": "ACCOUNT_RESTRICTED",
"errors": [
{
"path": [
"amount"
],
"message": "amount must be a whole number of smallest currency units (e.g. cents)"
}
]
}{
"status": 400,
"message": "Validation failed",
"code": "ACCOUNT_RESTRICTED",
"errors": [
{
"path": [
"amount"
],
"message": "amount must be a whole number of smallest currency units (e.g. cents)"
}
]
}{
"status": 404,
"message": "No deposit account exists for reference \"store-does-not-exist\". Issue one with that reference first."
}reference — you can send a deposit to one of them and confirm it lands against that reference and no other.
404 Not Found.Prerequisites
The account must already have an issued, active USD account. Issue one via Issue a Bank Account withcurrency: "USD". If none is provisioned, the call returns 404:
{
"status": 404,
"message": "No USD account is provisioned for this account yet. Issue a USD bank account first."
}
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, returned as payer.name. Defaults to "Sandbox Sender" when omitted. |
payment_rail | string | No | Rail the deposit should arrive on: ach (default), fedwire or swift. See Choosing the rail. |
bank_account_reference chooses which account receives the money; reference is a label on the transfer.Example Request
Credit the deposit account issued forstore-amazon-uk:
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.",
"payment_rail": "swift"
}'
Example Response
{
"status": 201,
"message": "Simulated USD deposit submitted",
"success": true,
"data": {
"status": "submitted",
"amount": "250.00",
"currency": "USD",
"reference": "RL_SIM_C029D665B02F",
"paymentRail": "swift",
"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. 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
Passpayment_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:
payment_rail sent | payment_rail on the deposit |
|---|---|
ach (default) | ach |
fedwire | wire_domestic |
swift | wire_international |
400.
What happens
- The request is routed to the USD provider’s sandbox, which submits a simulated incoming transfer against the deposit account you named. The response
statusissubmitted— the balance is not credited yet. - The provider then delivers a deposit webhook through the same crediting path a real deposit uses, and the wallet is credited.
- The transaction completes, emitting a
transaction.pendingevent followed bytransaction.completed, each carryingpayer.name(yoursender_name, or"Sandbox Sender") andpayment_rail. See Webhook Payloads.
submitted response always produces a deposit carrying them.submitted response, poll List Wallets or Transactions until the balance lands.Unknown references
Abank_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:
{
"status": 404,
"message": "No deposit account exists for reference \"store-does-not-exist\". Issue one with that reference first."
}
reference.Authorizations
Your Rolla API key
Path Parameters
Identifier of an account owned by the same user as your API key's business
"eec3cbed-79d8-4370-87a0-b6be9e287337"
Body
Deposit amount in major units of USD, e.g. "100" or "100.50". Must be greater than 0.
^\d+(\.\d{1,2})?$"250.00"
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.
1 - 100"store-amazon-uk"
Your own reference carried on the simulated transfer itself. Generated when omitted.
1 - 120Name recorded as the sender on the resulting transaction. Returned as payer.name. Defaults to "Sandbox Sender" when omitted.
1 - 120"Amazon EU S.a.r.l."
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.
ach, fedwire, swift "swift"