Simulate a Deposit (Sandbox)

curl --request POST \
  --url https://api.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",
  "reference": "<string>",
  "sender_name": "Amazon EU S.a.r.l."
}
'

import requests

url = "https://api.rolla.xyz/api/v1/external/accounts/{accountId}/bank-accounts/simulate-deposit"

payload = {
    "amount": "250.00",
    "bank_account_reference": "store-amazon-uk",
    "reference": "<string>",
    "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',
    reference: '<string>',
    sender_name: 'Amazon EU S.a.r.l.'
  })
};

fetch('https://api.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.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',
    'reference' => '<string>',
    '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.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  \"reference\": \"<string>\",\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.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  \"reference\": \"<string>\",\n  \"sender_name\": \"Amazon EU S.a.r.l.\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.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  \"reference\": \"<string>\",\n  \"sender_name\": \"Amazon EU S.a.r.l.\"\n}"

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

{
  "success": true,
  "message": "Simulated USD deposit submitted",
  "data": {
    "status": "submitted",
    "amount": "250.00",
    "currency": "USD",
    "reference": "RL_SIM_C029D665B02F",
    "bankAccountReference": "store-amazon-uk",
    "transferId": "<string>",
    "message": "<string>"
  }
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

Account Onboarding

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.

POST

accounts

{accountId}

bank-accounts

simulate-deposit

Simulate a Deposit (Sandbox)

curl --request POST \
  --url https://api.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",
  "reference": "<string>",
  "sender_name": "Amazon EU S.a.r.l."
}
'

import requests

url = "https://api.rolla.xyz/api/v1/external/accounts/{accountId}/bank-accounts/simulate-deposit"

payload = {
    "amount": "250.00",
    "bank_account_reference": "store-amazon-uk",
    "reference": "<string>",
    "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',
    reference: '<string>',
    sender_name: 'Amazon EU S.a.r.l.'
  })
};

fetch('https://api.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.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',
    'reference' => '<string>',
    '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.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  \"reference\": \"<string>\",\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.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  \"reference\": \"<string>\",\n  \"sender_name\": \"Amazon EU S.a.r.l.\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.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  \"reference\": \"<string>\",\n  \"sender_name\": \"Amazon EU S.a.r.l.\"\n}"

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

{
  "success": true,
  "message": "Simulated USD deposit submitted",
  "data": {
    "status": "submitted",
    "amount": "250.00",
    "currency": "USD",
    "reference": "RL_SIM_C029D665B02F",
    "bankAccountReference": "store-amazon-uk",
    "transferId": "<string>",
    "message": "<string>"
  }
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>"
}

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 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:

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

{
  "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

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.
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.pending event followed by transaction.completed. See Webhook Payloads.

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:

{
  "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. 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

Body

application/json

amount

string

required

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

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.

Maximum string length: 100

Example:

"store-amazon-uk"

reference

string

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

Maximum string length: 120

sender_name

string

Name recorded as the sender on the resulting transaction.

Maximum string length: 120

Example:

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

Response

Simulated deposit submitted

success

boolean

Example:

true

message

string

Example:

"Simulated USD deposit submitted"

data

object

Show child attributes

Overview

Banks

Account Lookup

Transactions

Wallet

Beneficiaries

Teams

Account Onboarding

Webhooks

Simulate an Account Deposit (Sandbox)

Prerequisites

Request Body

Example Request

Example Response

What happens

Unknown references

Authorizations

Path Parameters

Body

Response

​Prerequisites

​Request Body

​Example Request

​Example Response

​What happens

​Unknown references

Authorizations

Path Parameters

Body

Response

Prerequisites

Request Body

Example Request

Example Response

What happens

Unknown references