curl --request POST \
--url https://api-staging.rolla.xyz/api/v1/external/wallet/simulate-usd-deposit \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"amount": "100",
"sender_name": "John Sender"
}
'import requests
url = "https://api-staging.rolla.xyz/api/v1/external/wallet/simulate-usd-deposit"
payload = {
"amount": "100",
"sender_name": "John Sender"
}
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: '100', sender_name: 'John Sender'})
};
fetch('https://api-staging.rolla.xyz/api/v1/external/wallet/simulate-usd-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/wallet/simulate-usd-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' => '100',
'sender_name' => 'John Sender'
]),
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/wallet/simulate-usd-deposit"
payload := strings.NewReader("{\n \"amount\": \"100\",\n \"sender_name\": \"John Sender\"\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/wallet/simulate-usd-deposit")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": \"100\",\n \"sender_name\": \"John Sender\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-staging.rolla.xyz/api/v1/external/wallet/simulate-usd-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\": \"100\",\n \"sender_name\": \"John Sender\"\n}"
response = http.request(request)
puts response.read_body{
"status": 201,
"message": "Simulated USD deposit submitted",
"success": true,
"data": {
"status": "submitted",
"amount": "100",
"currency": "USD",
"reference": "RL_SIM_A7CAF7AC3673",
"bankAccountReference": null,
"transferId": "9d56e63c-2f2f-42b3-9ef7-1852677692cf",
"message": "Simulated incoming USD transfer submitted. The balance will be credited to the wallet via the provider webhook.",
"paymentRail": "fedwire"
}
}{
"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": 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 USD account is provisioned for this account yet. Issue a USD bank account first."
}Simulate a USD Deposit (Sandbox)
Sandbox only: simulates an incoming USD deposit into the account’s USD wallet. The request is dispatched to the account’s USD provider sandbox and the wallet is credited asynchronously via that provider’s deposit webhook, so the call only submits the transfer. The route does not exist in production, where it returns 404. Requires an issued, active USD account; it always credits the primary one.
curl --request POST \
--url https://api-staging.rolla.xyz/api/v1/external/wallet/simulate-usd-deposit \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"amount": "100",
"sender_name": "John Sender"
}
'import requests
url = "https://api-staging.rolla.xyz/api/v1/external/wallet/simulate-usd-deposit"
payload = {
"amount": "100",
"sender_name": "John Sender"
}
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: '100', sender_name: 'John Sender'})
};
fetch('https://api-staging.rolla.xyz/api/v1/external/wallet/simulate-usd-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/wallet/simulate-usd-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' => '100',
'sender_name' => 'John Sender'
]),
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/wallet/simulate-usd-deposit"
payload := strings.NewReader("{\n \"amount\": \"100\",\n \"sender_name\": \"John Sender\"\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/wallet/simulate-usd-deposit")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": \"100\",\n \"sender_name\": \"John Sender\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-staging.rolla.xyz/api/v1/external/wallet/simulate-usd-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\": \"100\",\n \"sender_name\": \"John Sender\"\n}"
response = http.request(request)
puts response.read_body{
"status": 201,
"message": "Simulated USD deposit submitted",
"success": true,
"data": {
"status": "submitted",
"amount": "100",
"currency": "USD",
"reference": "RL_SIM_A7CAF7AC3673",
"bankAccountReference": null,
"transferId": "9d56e63c-2f2f-42b3-9ef7-1852677692cf",
"message": "Simulated incoming USD transfer submitted. The balance will be credited to the wallet via the provider webhook.",
"paymentRail": "fedwire"
}
}{
"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": 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 USD account is provisioned for this account yet. Issue a USD bank account first."
}404 Not Found. Use it against your sandbox environment only.Prerequisites
The account must already have an issued, active USD account. Issue one first via Issue a Bank Account withcurrency: "USD". If no USD account is provisioned yet, the call returns 404:
{
"status": 404,
"message": "No USD account is provisioned for this account yet. Issue a USD bank account first."
}
X-Account-Id header. Without it the deposit is credited to your own business, which returns 404 if your business has no USD account of its own.
reference — use Simulate an Account Deposit instead, which can target one of them by reference.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. |
reference | string | No | Your own reference for the simulated transfer. If omitted, a reference is generated for you. |
sender_name | string | No | Name to record as the sender/counterparty on the 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. Reported on the deposit as ach, wire_domestic or wire_international — see Choosing the rail. |
Example Request
curl -X POST "https://api-staging.rolla.xyz/api/v1/external/wallet/simulate-usd-deposit" \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"amount": "100",
"sender_name": "John Sender",
"payment_rail": "fedwire"
}'
Example Response
{
"status": 201,
"message": "Simulated USD deposit submitted",
"success": true,
"data": {
"status": "submitted",
"amount": "100",
"currency": "USD",
"reference": "RL_SIM_A7CAF7AC3673",
"paymentRail": "fedwire",
"bankAccountReference": null,
"transferId": "9d56e63c-2f2f-42b3-9ef7-1852677692cf",
"message": "Simulated incoming USD transfer submitted. The balance will be credited to the wallet via the provider webhook."
}
}
reference is the one you sent, or the generated RL_SIM_... when you omitted it. bankAccountReference names which deposit account was credited and is null for the primary account, which is the only one this endpoint targets. bankAccountReference and transferId are only present when the USD provider’s sandbox reports them. A malformed body (for example a non-numeric amount) returns 400 with "message": "Validation failed" and an errors array; a rejection from the provider sandbox returns 400 with its message.
What happens
- The request is routed to your account’s USD provider sandbox, which submits a simulated incoming transfer against your USD account. The response
statusissubmitted— the balance is not credited yet. - The provider then delivers a deposit webhook through the same crediting path a real USD deposit uses, and your USD wallet is credited.
- The transaction is completed, emitting the deposit webhook to your configured endpoint: a
transaction.pendingevent, followed bytransaction.completed. Both carrypayer.name(yoursender_name, or"Sandbox Sender") andpayment_railfor the rail you chose. See Webhook Payloads.
submitted response, poll List Wallets or Transactions until the USD balance lands.Authorizations
Your Rolla API key
Headers
Tenant API keys only: credit a specific sub-account under your tenancy. Omit to use the calling account.
Body
Deposit amount in major units of USD. Must be greater than 0.
^\d+(\.\d{1,2})?$"100"
Your own reference for the simulated transfer. Generated as RL_SIM_... when omitted.
1 - 120Name to record as the sender/counterparty on the transaction. Returned as payer.name. Defaults to "Sandbox Sender" when omitted.
1 - 120"John Sender"
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 "fedwire"