Virtual Accounts

Overview

Virtual Accounts are U.S. bank accounts that automatically convert incoming USD deposits into cryptocurrency and route the funds to a designated blockchain wallet. When a payment is sent to a virtual account via ACH or wire transfer, the deposited USD is converted to USDC (or another supported token) and settled directly into the associated crypto wallet.

How It Works

User sends USD via ACH or wire to the virtual account
USD is received at the virtual account (1-3 days for ACH, same/next day for wire)
Instant conversion to USDC at current market rate
Blockchain settlement - crypto sent to user's wallet
Webhook notification - you're notified when deposit is complete

Prerequisites

Before creating virtual accounts, ensure:

✅ You're authenticated (Authenticate)
✅ User has been created (User Management)
✅ User is verified (Verification)
✅ User has a blockchain wallet (Solana or Polygon)

Use Cases

USD virtual accounts are ideal for:

👤 Freelancers - Receive payments from U.S. clients 🤝 Contractors - Get paid for project work 🏦 SMBs - Accept payments from U.S. customers 💼 Remote Workers - Receive salary in crypto

Guides in This Section

1. Virtual Accounts

📖 Virtual Accounts Guide

Learn how to:

Create virtual accounts for users
Get bank account details for deposits
Manage account status
Support multiple blockchains

Key topics:

Account types (US_ACH)
Supported currencies (USDC)
Supported networks (Solana, Polygon)
Bank deposit instructions
Account lifecycle

Endpoint: POST /v1/users/{userId}/virtual-accounts

2. Deposits

📖 Deposits Guide

Learn how to:

Track incoming deposits
View deposit history
Get blockchain transaction hashes
Calculate total received

Key topics:

Deposit lifecycle
Payment rails (ACH vs Wire)
Fees and amounts
Blockchain tracking
Real-time notifications

Endpoint: GET /virtual-accounts/{virtualAccountId}/deposits

3. Error Handling

📖 Error Handling Guide

Learn how to:

Handle common errors
Implement retry logic
Validate requests before sending
Debug integration issues

Key topics:

HTTP status codes
Error response format
Common error scenarios
Best practices
Circuit breaker pattern

Quick Start

1. Create Virtual Account

curl -X POST https://api.balampay.com/v1/users/{userId}/virtual-accounts \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: va-$(date +%s)" \
  -d '{
    "type": "US_ACH",
    "destination": {
      "currency": "USDC",
      "network": "solana",
      "address": "7tQJvFk8XZoaVRjL..."
    },
    "description": "Primary receiving account"
  }'

2. Get Bank Details

Response includes source_deposit_instructions:

{
  "id": "va_789012345",
  "status": "active",
  "source_deposit_instructions": {
    "bank_name": "Partner Bank",
    "bank_account_number": "1234567890",
    "bank_routing_number": "021000021",
    "bank_beneficiary_name": "John Doe",
    "bank_beneficiary_address": "123 Main St, City, State 12345"
  },
  "destination": {
    "currency": "USDC",
    "network": "solana",
    "address": "7tQJvFk8XZoaVRjL..."
  }
}

3. User Shares Bank Details

Share the bank details with the user so they can receive payments:

To receive payments, share these details:

Bank Name: Partner Bank
Account Number: 1234567890
Routing Number: 021000021
Beneficiary: John Doe

⏱️ ACH: 1-3 business days
⏱️ Wire: Same day or next day

💡 USD automatically converts to USDC and sends to your wallet

4. Track Deposits

curl -X GET "https://api.balampay.com/virtual-accounts/va_789012345/deposits?limit=50" \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-api-key: $API_KEY"

Response:

[
  {
    "id": "dep_abc123",
    "amount": "1000.00",
    "currency": "usdc",
    "source": {
      "payment_rail": "ach_push",
      "sender_name": "Acme Corporation"
    },
    "destination_tx_hash": "5KYmFMZ3qvX...",
    "created_at": "2024-01-15T14:30:00Z"
  }
]

Supported Configurations

Currency	Network	Status
USDC	Solana	✅ Supported
USDC	Polygon	✅ Supported

Payment Rails

ACH Transfer

Speed: 1-3 business days
Cost: Low/free for sender
Limits: Typically $25K - $1M per transaction

Wire Transfer

Speed: Same day or next day
Cost: $15-$50 for sender
Limits: Typically unlimited
Types: Domestic and international

Webhooks

Receive real-time notifications when deposits are processed. Webhook events are sent at different stages of the deposit lifecycle:

Deposit Received:

{
  "event": "virtual_account.deposit_funds_received",
  "data": {
    "virtual_account_id": "va_123",
    "amount": "1000.00",
    "currency": "usdc",
    "source": {
      "payment_rail": "ach_push",
      "sender_name": "Acme Corporation",
      "sender_bank_routing_number": "021000021",
      "trace_number": "123456789",
      "description": "Payment from sender"
    },
    "created_at": "2024-01-15T14:30:00Z"
  }
}

Funds in Transit:

{
  "event": "virtual_account.deposit_funds_in_transit",
  "data": {
    "virtual_account_id": "va_123",
    "amount": "1000.00",
    "currency": "usdc",
    "created_at": "2024-01-15T14:32:00Z"
  }
}

Funds in Destination:

{
  "event": "virtual_account.deposit_funds_in_destination",
  "data": {
    "virtual_account_id": "va_123",
    "amount": "1000.00",
    "currency": "usdc",
    "destination_tx_hash": "5KYmFMZ3qvX...",
    "created_at": "2024-01-15T14:35:00Z"
  }
}

Other Events:

virtual_account.deposit_scheduled - Deposit has been scheduled
virtual_account.deposit_in_review - Deposit is under review
virtual_account.deposit_funds_refunded - Funds have been refunded

See the Webhooks Guide for setup instructions.

Complete Flow Diagram

sequenceDiagram
    participant User
    participant Your App
    participant Kira API
    participant Payment Provider
    participant Blockchain

    Note over Your App: Prerequisites: User created & verified

    Your App->>Kira API: POST /v1/users/{userId}/virtual-accounts
    Kira API->>Payment Provider: Create Virtual Account
    Payment Provider-->>Kira API: Bank Account Details
    Kira API-->>Your App: Virtual Account + Bank Details

    Your App->>User: Share Bank Details

    Note over User,Payment Provider: User receives USD payment

    User->>Payment Provider: USD Transfer (ACH/Wire)
    Payment Provider->>Payment Provider: Convert USD → USDC
    Payment Provider->>Blockchain: Send USDC to Wallet
    Blockchain-->>Payment Provider: Transaction Confirmed

    Payment Provider->>Kira API: Webhook: Deposit Processed
    Kira API->>Your App: Webhook: Deposit Notification

    Your App->>Kira API: GET /virtual-accounts/{id}/deposits
    Kira API-->>Your App: Deposit History

Quick Reference

For quick API reference, see:

📖 Quick Reference Guide

Includes:

All endpoints at a glance
Request examples
Status codes
Error codes

Support

Email: [email protected]
Full Virtual Accounts Guide: virtual-accounts
Full Deposits Guide: deposits
Error Handling: error-handling

Overview

How It Works

Prerequisites

Use Cases

Guides in This Section

1. Virtual Accounts

2. Deposits

3. Error Handling

Quick Start

1. Create Virtual Account

2. Get Bank Details

3. User Shares Bank Details

4. Track Deposits

Supported Configurations

Payment Rails

ACH Transfer

Wire Transfer

Webhooks

Complete Flow Diagram

Quick Reference

Related Documentation

Support