Simulate a USD Deposit (Sandbox)

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",
  "reference": "<string>",
  "sender_name": "John Sender"
}
'

import requests

url = "https://api-staging.rolla.xyz/api/v1/external/wallet/simulate-usd-deposit"

payload = {
    "amount": "100",
    "reference": "<string>",
    "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', reference: '<string>', 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',
    'reference' => '<string>',
    '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  \"reference\": \"<string>\",\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  \"reference\": \"<string>\",\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  \"reference\": \"<string>\",\n  \"sender_name\": \"John Sender\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": 201,
  "success": true,
  "message": "Simulated USD deposit submitted",
  "data": {
    "status": "submitted",
    "amount": "100",
    "currency": "USD",
    "reference": "RL_SIM_A7CAF7AC3673",
    "transferId": "9d56e63c-2f2f-42b3-9ef7-1852677692cf",
    "message": "Simulated incoming USD transfer submitted. The balance will be credited to the wallet via the provider webhook."
  }
}

POST

wallet

simulate-usd-deposit

Simulate a USD Deposit (Sandbox)

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",
  "reference": "<string>",
  "sender_name": "John Sender"
}
'

import requests

url = "https://api-staging.rolla.xyz/api/v1/external/wallet/simulate-usd-deposit"

payload = {
    "amount": "100",
    "reference": "<string>",
    "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', reference: '<string>', 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',
    'reference' => '<string>',
    '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  \"reference\": \"<string>\",\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  \"reference\": \"<string>\",\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  \"reference\": \"<string>\",\n  \"sender_name\": \"John Sender\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": 201,
  "success": true,
  "message": "Simulated USD deposit submitted",
  "data": {
    "status": "submitted",
    "amount": "100",
    "currency": "USD",
    "reference": "RL_SIM_A7CAF7AC3673",
    "transferId": "9d56e63c-2f2f-42b3-9ef7-1852677692cf",
    "message": "Simulated incoming USD transfer submitted. The balance will be credited to the wallet via the provider webhook."
  }
}

A testing helper that simulates an incoming USD deposit into your account’s USD wallet so you can verify your USD funding flow end-to-end — the wallet is credited and the deposit webhook is delivered — without sending a real wire transfer. It is the USD counterpart of Simulate a Deposit. The request is dispatched to your account’s USD provider sandbox; the wallet balance is then credited asynchronously via that provider’s normal deposit webhook — so the call only submits the simulated inbound transfer.

Sandbox / testing only. This endpoint does not exist in production — calls to the production API return 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 with currency: "USD". If no USD account is provisioned yet, the call returns 404 with code USD_ACCOUNT_NOT_FOUND. To simulate a deposit for a specific sub-account under your tenancy, send its id in the 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.

This endpoint always credits the client’s primary USD account. If the client holds several deposit accounts — one per 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.

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"
  }'

Example Response

{
  "status": 201,
  "success": true,
  "message": "Simulated USD deposit submitted",
  "data": {
    "status": "submitted",
    "amount": "100",
    "currency": "USD",
    "reference": "RL_SIM_A7CAF7AC3673",
    "transferId": "9d56e63c-2f2f-42b3-9ef7-1852677692cf",
    "message": "Simulated incoming USD transfer submitted. The balance will be credited to the wallet via the provider webhook."
  }
}

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 status is submitted — 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.pending event, followed by transaction.completed. See Webhook Payloads.

Because the credit is delivered by the provider webhook, it is not instant. After a submitted response, poll List Wallets or Transactions until the USD balance lands.

Because this credits a real (sandbox) wallet balance, treat it like any other write: it moves your test wallet’s balance and generates a real transaction record and webhook delivery.

Authorizations

X-API-Key

string

header

required

Your Rolla API key

Headers

X-Account-Id

string<uuid>

Target a specific sub-account under your tenancy. Omit to use the calling account.

Body

application/json

amount

string

required

Deposit amount in major units of USD. Must be greater than 0.

Example:

"100"

reference

string

Your own reference for the simulated transfer. Auto-generated if omitted.

Maximum string length: 120

sender_name

string

Name to record as the sender/counterparty on the transaction.

Maximum string length: 120

Example:

"John Sender"

Response

Simulated USD deposit submitted

Overview

Banks

Account Lookup

Transactions

Wallet

Beneficiaries

Teams

Account Onboarding

Webhooks

Simulate a USD Deposit (Sandbox)

Prerequisites

Request Body

Example Request

Example Response

What happens

Authorizations

Headers

Body

Response

​Prerequisites

​Request Body

​Example Request

​Example Response

​What happens

Authorizations

Headers

Body

Response

Prerequisites

Request Body

Example Request

Example Response

What happens