Deposits

Overview

Once a virtual account is created and active, it can receive deposits via bank transfers. The deposit behavior depends on the virtual account mode:

• Crypto Mode: Deposits are automatically converted to stablecoins (USDC or USDT) and sent to the configured destination wallet
• Fiat Mode: Deposits are added to the virtual account's USD balance

Get Deposits

List Deposits by Virtual Account

GET /v1/virtual-accounts/{virtualAccountId}/deposits

Query Parameters

Example Request

curl -X GET "https://api.balampay.com/v1/virtual-accounts/550e8400-e29b-41d4-a716-446655440001/deposits?limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY"

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440010",
    "virtual_account_id": "550e8400-e29b-41d4-a716-446655440001",
    "amount": "1000.00",
    "currency": "USD",
    "status": "COMPLETED",
    "sender": {
      "name": "Acme Corporation",
      "account_number": null,
      "address": null
    },
    "recipient": {
      "name": "John Doe",
      "company_name": "Acme Corp",
      "country": "US"
    },
    "payment_rail": "wire",
    "settlement_tx_hash": "5KYmFMZ3qvX7h8sN...",
    "created_at": "2024-01-15T14:30:05Z",
    "updated_at": "2024-01-15T14:30:05Z"
  }
]

List Deposits by Client

Returns deposits across all virtual accounts for the authenticated client, with pagination.

GET /v1/virtual-accounts/deposits

Query Parameters

Example Request

curl -X GET "https://api.balampay.com/v1/virtual-accounts/deposits?page=1&limit=20&status=COMPLETED" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "deposits": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "virtual_account_id": "550e8400-e29b-41d4-a716-446655440001",
      "amount": "1000.00",
      "currency": "USD",
      "status": "COMPLETED",
      "sender": {
        "name": "Acme Corporation",
        "account_number": null,
        "address": null
      },
      "recipient": {
        "name": "John Doe",
        "company_name": "Acme Corp",
        "country": "US"
      },
      "payment_rail": "wire",
      "settlement_tx_hash": "5KYmFMZ3qvX7h8sN...",
      "created_at": "2024-01-15T14:30:05Z",
      "updated_at": "2024-01-15T14:30:05Z"
    }
  ],
  "total": 47,
  "page": 1,
  "limit": 20,
  "total_pages": 3
}

Get Single Deposit

GET /v1/virtual-accounts/{virtualAccountId}/deposits/{depositId}

Path Parameters

Example Request

curl -X GET "https://api.balampay.com/v1/virtual-accounts/550e8400-e29b-41d4-a716-446655440001/deposits/550e8400-e29b-41d4-a716-446655440010" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440010",
  "virtual_account_id": "550e8400-e29b-41d4-a716-446655440001",
  "amount": "1000.00",
  "currency": "USD",
  "status": "COMPLETED",
  "sender": {
    "name": "Acme Corporation",
    "account_number": null,
    "address": null
  },
  "recipient": {
    "name": "John Doe",
    "company_name": "Acme Corp",
    "country": "US"
  },
  "payment_rail": "wire",
  "settlement_tx_hash": "5KYmFMZ3qvX7h8sN...",
  "created_at": "2024-01-15T14:30:05Z",
  "updated_at": "2024-01-15T14:30:05Z"
}

Deposit Response Fields

Deposit Status

Deposit Lifecycle

Crypto Mode

When a deposit arrives at a crypto mode VA, the system automatically converts the funds and sends stablecoins to the destination wallet:

sequenceDiagram
    participant Sender
    participant Sender Bank
    participant Kira
    participant Your Server
    participant Blockchain

    Sender->>Sender Bank: Initiate ACH/Wire transfer
    Sender Bank->>Kira: Transfer USD
    Note over Kira: Create deposit (status: completed)
    Kira->>Your Server: Webhook: virtual_account.deposit_funds_received

    Note over Kira: Convert USD to stablecoins
    Kira->>Your Server: Webhook: virtual_account.deposit_funds_in_transit
    Kira->>Blockchain: Send stablecoins to destination wallet
    Blockchain-->>Kira: Transaction confirmed
    Kira->>Your Server: Webhook: virtual_account.deposit_funds_in_destination

Note: Deposits under $1.00 USD are treated as microdeposits. A deposit_funds_received webhook is sent but no crypto settlement is triggered.

Settlement Webhook Events

See the Webhooks Guide for full payload structures.

Fiat Mode

In fiat mode, deposits increase the virtual account balance. No conversion or settlement occurs.

sequenceDiagram
    participant Sender
    participant Sender Bank
    participant Kira
    participant Your Server

    Sender->>Sender Bank: Initiate ACH/Wire transfer
    Sender Bank->>Kira: Transfer USD
    Note over Kira: Create deposit (status: completed)
    Note over Kira: Balance updated
    Kira->>Your Server: Webhook: virtual_account.deposit_funds_received

Use GET /v1/virtual-accounts/{id}/balance to check the current balance.

Payment Rails

Wire / Swift Transfer

payment_rail returns wire for domestic transfers and swift for international transfers.

ACH Push

Best Practices

1. Use webhooks for real-time updates - Listen for virtual_account.deposit_funds_received to get notified when deposits arrive
2. Store deposit IDs - Track processed deposits using deposit_id to avoid duplicates
3. Handle refunds - Check for status: "refunded" deposits and update your records accordingly
4. Use limit parameter - Paginate results for accounts with many deposits

Troubleshooting

Deposit not showing up

• ACH transfers take 1-3 business days to arrive
• Wire transfers may still be processing (check with sender's bank)
• Verify sender used correct account/routing numbers
• Contact support with the transfer reference number

Deposit shows as refunded

• Compliance rejection or sender bank initiated a return
• Review the webhook payload for context
• Contact support with the deposit ID

Next Steps

1. Set up webhooks for real-time deposit notifications
2. Initiate payouts to send USD to any bank account (fiat and crypto mode)
3. Review the Webhooks Guide for complete event reference