Simulate a deposit

POST

virtual-accounts

{virtual_account_id}

simulate-deposit

Simulate a deposit

curl --request POST \
  --url https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/simulate-deposit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "via_provider": true,
  "amount": "100.00",
  "payment_type": "wire"
}
'

import requests

url = "https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/simulate-deposit"

payload = {
    "via_provider": True,
    "amount": "100.00",
    "payment_type": "wire"
}
headers = {
    "Authorization": "Bearer <token>",
    "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: {
    Authorization: 'Bearer <token>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({via_provider: true, amount: '100.00', payment_type: 'wire'})
};

fetch('https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/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.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/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([
    'via_provider' => true,
    'amount' => '100.00',
    'payment_type' => 'wire'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/simulate-deposit"

	payload := strings.NewReader("{\n  \"via_provider\": true,\n  \"amount\": \"100.00\",\n  \"payment_type\": \"wire\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/simulate-deposit")
  .header("Authorization", "Bearer <token>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"via_provider\": true,\n  \"amount\": \"100.00\",\n  \"payment_type\": \"wire\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/simulate-deposit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"via_provider\": true,\n  \"amount\": \"100.00\",\n  \"payment_type\": \"wire\"\n}"

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

{
  "accepted": true,
  "virtual_account_id": "3f6c1e8a-91d4-4f2b-9c07-5a1b8e2d4c60",
  "message": "The provider was asked to report this deposit. Poll the deposits endpoint to watch it land."
}

Sandbox only. Production has no route for this call and answers 404 route_not_found, so this page lists one base URL instead of two. There is no production equivalent — a real deposit is what production has.

It returns as soon as the bank has been asked. No deposit exists yet — one appears when the bank’s callback lands, so read List virtual account deposits or wait for the virtual_account.deposit_funds_received webhook. Nothing in the response identifies the deposit, because it has not been created.

Authorizations

Authorization

string

header

required

The data.access_token value from Get access token.

x-api-key

string

header

required

API key issued by Kira.

Headers

X-Api-Version

string

Version applied to this request. It wins over your account's pinned version — see Versioning.

Example:

"2026-06-01"

Path Parameters

virtual_account_id

string<uuid>

required

The virtual account to deposit into. It has to be one of yours, and active.

Example:

"3f6c1e8a-91d4-4f2b-9c07-5a1b8e2d4c60"

Body

application/json

via_provider

boolean

required

Reports the deposit through the bank instead of writing one directly. Anything other than true is refused rather than reinterpreted.

amount

string

required

How much to deposit in USD, as a positive decimal string with up to 2 decimals.

Example:

"100.00"

payment_type

enum<string>

default:wire

The rail the deposit arrives on.

Available options:

wire,

ach

Response

The bank was asked to report the deposit.

An acknowledgement, not a deposit.

accepted

boolean

Always true. A refusal arrives as a 400 or a 404 instead.

virtual_account_id

string

The account the deposit was asked for.

Example:

"3f6c1e8a-91d4-4f2b-9c07-5a1b8e2d4c60"

message

string

What happens next, in one sentence.

Simulate a deposit

curl --request POST \
  --url https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/simulate-deposit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "via_provider": true,
  "amount": "100.00",
  "payment_type": "wire"
}
'

import requests

url = "https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/simulate-deposit"

payload = {
    "via_provider": True,
    "amount": "100.00",
    "payment_type": "wire"
}
headers = {
    "Authorization": "Bearer <token>",
    "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: {
    Authorization: 'Bearer <token>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({via_provider: true, amount: '100.00', payment_type: 'wire'})
};

fetch('https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/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.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/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([
    'via_provider' => true,
    'amount' => '100.00',
    'payment_type' => 'wire'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/simulate-deposit"

	payload := strings.NewReader("{\n  \"via_provider\": true,\n  \"amount\": \"100.00\",\n  \"payment_type\": \"wire\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/simulate-deposit")
  .header("Authorization", "Bearer <token>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"via_provider\": true,\n  \"amount\": \"100.00\",\n  \"payment_type\": \"wire\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/simulate-deposit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"via_provider\": true,\n  \"amount\": \"100.00\",\n  \"payment_type\": \"wire\"\n}"

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

{
  "accepted": true,
  "virtual_account_id": "3f6c1e8a-91d4-4f2b-9c07-5a1b8e2d4c60",
  "message": "The provider was asked to report this deposit. Poll the deposits endpoint to watch it land."
}

Across the API

Authentication

Versioning

Users

Virtual Accounts

Recipients

Quotations

Payouts

Catalogs

RFIs

Simulate a deposit

Authorizations

Headers

Path Parameters

Body

Response