Get a deposit

GET

virtual-accounts

{virtual_account_id}

deposits

{deposit_id}

Get a deposit

curl --request GET \
  --url https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/deposits/{deposit_id} \
  --header 'Authorization: Bearer <token>'

import requests

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

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/deposits/{deposit_id}', 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}/deposits/{deposit_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/deposits/{deposit_id}")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "id": "5c6d7e80-9fa0-4b1c-8d2e-3f4a5b6c7d8e",
  "virtual_account_id": "11111111-2222-3333-4444-555555555555",
  "amount": "100.00000000",
  "currency": "USDT",
  "status": "COMPLETED",
  "rfi": null,
  "sender": {
    "name": null,
    "account_number": null,
    "address": "TD5gsCwxykWsLN9aPrq2TAfNjByuZKYp4E"
  },
  "recipient": {
    "name": "Alice Smith",
    "company_name": "Northwind Trading LLC",
    "country": "MEX"
  },
  "payment_rail": "stablecoin",
  "settlement_tx_hash": null,
  "source": {
    "name": null,
    "account_number": null,
    "address": "TD5gsCwxykWsLN9aPrq2TAfNjByuZKYp4E",
    "payment_rail": "stablecoin",
    "reference_number": null,
    "imad": null,
    "omad": null,
    "trace_number": null,
    "network": "tron",
    "tx_hash": "84ae83cab526664b44ee51b6f811ab04b2525de2010f8a9c026020a4df486f89"
  },
  "fees": {
    "base_fees": {
      "fixed_fee": "3.10",
      "percentage_fee": "0.08",
      "fx_markup": "0.06"
    },
    "client_markup": {
      "fixed_fee": "0.00",
      "percentage_fee": "0.00",
      "fx_markup": "0.00"
    },
    "total_fees": "3.24"
  },
  "net_amount": "96.76",
  "net_currency": "USD",
  "fee_total": "3.24",
  "fee_currency": "USD",
  "markup_total": "0.00",
  "quotation": {
    "quote_id": "9d8c7b60-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
    "quote_expires_at": "2026-10-13 03:20:46.859+00",
    "source": {
      "amount": 10000,
      "currency": "USD",
      "precision": 2
    },
    "recipient": {
      "amount": 9676,
      "currency": "USD",
      "precision": 2
    },
    "pricing_context": {
      "tier": "tier_1",
      "starting_tier": "tier_1",
      "intro_period_active": false,
      "transactional_waived": false,
      "month_cumulative": 0,
      "month_cumulative_currency": "USDT",
      "from_held_balance": false
    },
    "conversion": {
      "pair": "USDT/USD",
      "rate": "1.000000",
      "source_amount": 9676,
      "source_currency": "USD",
      "target_amount": 9676,
      "target_currency": "USD",
      "rate_source": "kraken",
      "market_rate": "1.000000",
      "clamp": "passthrough",
      "locked_at": "2026-10-13 03:20:46.867+00",
      "ttl_seconds": 900
    },
    "fees": [
      {
        "code": "inbound",
        "status": "active",
        "version": "v1",
        "deprecated_at": null,
        "charged_by": "kira",
        "amount": 8,
        "currency": "USD",
        "precision": 2,
        "kind": "percentage",
        "calculation_method": "percentage",
        "rate_bps": 8,
        "basis_amount": 10000,
        "basis_currency": "USD"
      },
      {
        "code": "conversion_off_ramp",
        "status": "active",
        "version": "v1",
        "deprecated_at": null,
        "charged_by": "kira",
        "amount": 6,
        "currency": "USD",
        "precision": 2,
        "kind": "percentage",
        "calculation_method": "percentage",
        "rate_bps": 6,
        "basis_amount": 10000,
        "basis_currency": "USD"
      },
      {
        "code": "tron_inbound",
        "status": "active",
        "version": "v1",
        "deprecated_at": null,
        "charged_by": "kira",
        "amount": 310,
        "currency": "USD",
        "precision": 2,
        "kind": "fixed"
      }
    ],
    "totals": {
      "kira_revenue_total": 324,
      "client_markup_total": 0,
      "fee_total": 324,
      "source_net_amount": 9676,
      "currency": "USD",
      "precision": 2
    }
  },
  "depeg_cost": "0.00",
  "events": [
    {
      "stage": "received",
      "created_at": "2026-10-13T03:20:46.829Z"
    },
    {
      "stage": "under_review",
      "created_at": "2026-10-13T03:20:47.009Z"
    },
    {
      "stage": "approved",
      "created_at": "2026-10-13T03:20:47.723Z"
    },
    {
      "stage": "in_transit",
      "created_at": "2026-10-13T03:20:47.794Z"
    },
    {
      "stage": "credited",
      "created_at": "2026-10-13T03:20:55.398Z"
    }
  ],
  "created_at": "2026-10-13T03:20:46.829Z",
  "updated_at": "2026-10-13T03:20:55.393Z",
  "metadata": {}
}

{
  "error": "Invalid request data",
  "details": [
    {
      "path": "depositId",
      "message": "Invalid deposit ID format",
      "code": "invalid_string"
    }
  ]
}

{
  "code": "invalid_request",
  "message": "The request could not be matched to a valid route, or was malformed. Verify the path and HTTP method against the API reference. This is a routing or request error, not a credentials or signature problem."
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Deposit 5c6d7e80-9fa0-4b1c-8d2e-3f4a5b6c7d8e not found",
  "timestamp": "2026-10-15T21:48:41.530Z",
  "path": "/v1/virtual-accounts/11111111-2222-3333-4444-555555555555/deposits/5c6d7e80-9fa0-4b1c-8d2e-3f4a5b6c7d8e"
}

Authorizations

Authorization

string

header

required

The data.access_token value from Get access token.

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

UUID of the account the deposit arrived in.

deposit_id

string<uuid>

required

UUID of the deposit, as id in a deposit list or deposit_id in a deposit webhook.

Response

The deposit.

One deposit.

source repeats what sender holds and adds the rail and its tracking numbers. Both are null together, when the bank has not told us who sent the money.

string<uuid>

Deposit UUID.

virtual_account_id

string<uuid>

UUID of the account the money arrived in.

amount

string

How much arrived, before charges, as a decimal string.

currency

string

Currency of amount.

status

string

Where the deposit has got to — see Virtual account values. Available options: PENDING, COMPLETED, FAILED, REFUNDED, KYT_PENDING, KYT_REJECTED, NEEDS_ACTION.

sender

object | null

Who sent the money, as the bank reported it.

Show child attributes

recipient

object

The user who owns the account the money arrived in. Every field is null if that user can no longer be read.

Show child attributes

payment_rail

string | null

How the money travelled, such as wire or ach_push. Mirrors source.payment_rail.

settlement_tx_hash

string | null

On-chain transaction that settled the deposit, the same as settlement.tx_hash. null on a fiat account, and until settlement runs.

source

object | null

Who sent the money, plus what the rail recorded about the transfer.

Show child attributes

fees

object

What was charged on this deposit. Every figure is a decimal string, and they are all 0.00 when nothing was charged. On a crypto inbound they read 0.00 until it is COMPLETED, and stay 0.00 if it is not credited.

Show child attributes

net_amount

string

What reaches the account, as a decimal string, never below 0.00. It is what was credited only once status is COMPLETED; before that it is what is expected to be credited, and a FAILED, KYT_REJECTED or REFUNDED deposit credited nothing, whatever this reads. A crypto inbound stopped before it was priced shows the tokens that arrived, with the token in net_currency.

net_currency

string

Currency of net_amount: USD once the deposit is priced, otherwise the currency it arrived in.

fee_total

string

Everything charged on this deposit, your markup included, as a decimal string: the same figure as fees.total_fees.

fee_currency

string

Currency of fee_total, the same as net_currency.

markup_total

string

The part of fee_total that is your own markup (fees.client_markup), as a decimal string. 0.00 when none was charged.

quotation

object

The itemized price a crypto inbound was converted at: every fee line, the totals and the rate, shaped like the quotation object. Absent on every other deposit.

depeg_cost

string

What the conversion did not credit because the token traded below one dollar, as a decimal string. It is part of the rate, not a fee, so it is in no fee line: see How you're charged. 0.00 at par. Present only with quotation.

events

object[]

The stages the deposit went through, oldest first. Only a crypto inbound records them; every other deposit returns []. Absent when the stages could not be read.

Show child attributes

settlement

object | null

What a crypto-mode account converted the deposit into and sent to its wallet, read from the send itself, so a later change to the account's destination never rewrites it. null on a fiat account, and until the deposit settles: the account's mode tells which.

Show child attributes

created_at

string

When the deposit was first recorded, as an ISO 8601 timestamp.

updated_at

string

When it last changed, as an ISO 8601 timestamp.

metadata

object

Key/value pairs attached to the deposit. {} when there are none.

rfi

object | null

The open request for information holding this deposit, or null. Present whenever status reads NEEDS_ACTION, and names the request to answer.

Show child attributes

Example:

{
  "rfi_id": "7f1c9a20-3b4d-4e5f-8a91-2c3d4e5f6a7b",
  "status": "pending",
  "due_at": "2026-09-15T23:59:59.000Z"
}

Get a deposit

curl --request GET \
  --url https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/deposits/{deposit_id} \
  --header 'Authorization: Bearer <token>'

import requests

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

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/deposits/{deposit_id}', 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}/deposits/{deposit_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.balampay.com/sandbox/v1/virtual-accounts/{virtual_account_id}/deposits/{deposit_id}")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "id": "5c6d7e80-9fa0-4b1c-8d2e-3f4a5b6c7d8e",
  "virtual_account_id": "11111111-2222-3333-4444-555555555555",
  "amount": "100.00000000",
  "currency": "USDT",
  "status": "COMPLETED",
  "rfi": null,
  "sender": {
    "name": null,
    "account_number": null,
    "address": "TD5gsCwxykWsLN9aPrq2TAfNjByuZKYp4E"
  },
  "recipient": {
    "name": "Alice Smith",
    "company_name": "Northwind Trading LLC",
    "country": "MEX"
  },
  "payment_rail": "stablecoin",
  "settlement_tx_hash": null,
  "source": {
    "name": null,
    "account_number": null,
    "address": "TD5gsCwxykWsLN9aPrq2TAfNjByuZKYp4E",
    "payment_rail": "stablecoin",
    "reference_number": null,
    "imad": null,
    "omad": null,
    "trace_number": null,
    "network": "tron",
    "tx_hash": "84ae83cab526664b44ee51b6f811ab04b2525de2010f8a9c026020a4df486f89"
  },
  "fees": {
    "base_fees": {
      "fixed_fee": "3.10",
      "percentage_fee": "0.08",
      "fx_markup": "0.06"
    },
    "client_markup": {
      "fixed_fee": "0.00",
      "percentage_fee": "0.00",
      "fx_markup": "0.00"
    },
    "total_fees": "3.24"
  },
  "net_amount": "96.76",
  "net_currency": "USD",
  "fee_total": "3.24",
  "fee_currency": "USD",
  "markup_total": "0.00",
  "quotation": {
    "quote_id": "9d8c7b60-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
    "quote_expires_at": "2026-10-13 03:20:46.859+00",
    "source": {
      "amount": 10000,
      "currency": "USD",
      "precision": 2
    },
    "recipient": {
      "amount": 9676,
      "currency": "USD",
      "precision": 2
    },
    "pricing_context": {
      "tier": "tier_1",
      "starting_tier": "tier_1",
      "intro_period_active": false,
      "transactional_waived": false,
      "month_cumulative": 0,
      "month_cumulative_currency": "USDT",
      "from_held_balance": false
    },
    "conversion": {
      "pair": "USDT/USD",
      "rate": "1.000000",
      "source_amount": 9676,
      "source_currency": "USD",
      "target_amount": 9676,
      "target_currency": "USD",
      "rate_source": "kraken",
      "market_rate": "1.000000",
      "clamp": "passthrough",
      "locked_at": "2026-10-13 03:20:46.867+00",
      "ttl_seconds": 900
    },
    "fees": [
      {
        "code": "inbound",
        "status": "active",
        "version": "v1",
        "deprecated_at": null,
        "charged_by": "kira",
        "amount": 8,
        "currency": "USD",
        "precision": 2,
        "kind": "percentage",
        "calculation_method": "percentage",
        "rate_bps": 8,
        "basis_amount": 10000,
        "basis_currency": "USD"
      },
      {
        "code": "conversion_off_ramp",
        "status": "active",
        "version": "v1",
        "deprecated_at": null,
        "charged_by": "kira",
        "amount": 6,
        "currency": "USD",
        "precision": 2,
        "kind": "percentage",
        "calculation_method": "percentage",
        "rate_bps": 6,
        "basis_amount": 10000,
        "basis_currency": "USD"
      },
      {
        "code": "tron_inbound",
        "status": "active",
        "version": "v1",
        "deprecated_at": null,
        "charged_by": "kira",
        "amount": 310,
        "currency": "USD",
        "precision": 2,
        "kind": "fixed"
      }
    ],
    "totals": {
      "kira_revenue_total": 324,
      "client_markup_total": 0,
      "fee_total": 324,
      "source_net_amount": 9676,
      "currency": "USD",
      "precision": 2
    }
  },
  "depeg_cost": "0.00",
  "events": [
    {
      "stage": "received",
      "created_at": "2026-10-13T03:20:46.829Z"
    },
    {
      "stage": "under_review",
      "created_at": "2026-10-13T03:20:47.009Z"
    },
    {
      "stage": "approved",
      "created_at": "2026-10-13T03:20:47.723Z"
    },
    {
      "stage": "in_transit",
      "created_at": "2026-10-13T03:20:47.794Z"
    },
    {
      "stage": "credited",
      "created_at": "2026-10-13T03:20:55.398Z"
    }
  ],
  "created_at": "2026-10-13T03:20:46.829Z",
  "updated_at": "2026-10-13T03:20:55.393Z",
  "metadata": {}
}

{
  "error": "Invalid request data",
  "details": [
    {
      "path": "depositId",
      "message": "Invalid deposit ID format",
      "code": "invalid_string"
    }
  ]
}

{
  "code": "invalid_request",
  "message": "The request could not be matched to a valid route, or was malformed. Verify the path and HTTP method against the API reference. This is a routing or request error, not a credentials or signature problem."
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Deposit 5c6d7e80-9fa0-4b1c-8d2e-3f4a5b6c7d8e not found",
  "timestamp": "2026-10-15T21:48:41.530Z",
  "path": "/v1/virtual-accounts/11111111-2222-3333-4444-555555555555/deposits/5c6d7e80-9fa0-4b1c-8d2e-3f4a5b6c7d8e"
}

Across the API

Authentication

Versioning

Users

Virtual Accounts

Recipients

Quotations

Payouts

Ultimate Payors

Capabilities

Catalogs

RFIs

Authorizations

Headers

Path Parameters

Response