Balance

Documentation Index

Fetch the complete documentation index at: https://docs.gate.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

• Balance Query: Real-time available balance by currency
• Order Fee Query: Verify fees and settlement amounts at the order level
• Funds Ledger Query: Track all fund movements by transaction

​

Balance Query

​

Common Use Cases

• Pre-settlement validation: Confirm available balance before initiating settlement
• Period-end snapshots: Capture balance at close of business for accounting
• Operational monitoring: Real-time balance alerts and thresholds
• Multi-currency management: Track balances across different currencies

​

API Reference

​

Request Parameters

​

Response Fields

​

Example Request

curl -X GET "https://api.gatepay.io/v1/pay/balance/query?currencies=USDT,BTC,USD" \
  -H "X-GatePay-Certificate-ClientId: your_client_id" \
  -H "X-GatePay-Timestamp: 1704067200000" \
  -H "X-GatePay-Nonce: abc123def456" \
  -H "X-GatePay-Signature: your_signature" \

​

Example Response

{
  "data": [
    {
      "currency": "USDT",
      "available": "10500.50",
      "hold": "499.50",
      "total": "11000.00",
      "last_updated": 1704067205000
    },
    {
      "currency": "BTC",
      "available": "0.25",
      "hold": "0.05",
      "total": "0.30",
      "last_updated": 1704067205000
    },
    {
      "currency": "USD",
      "available": "25000.00",
      "hold": "0.00",
      "total": "25000.00",
      "last_updated": 1704067205000
    }
  ]
}

​

Integration Steps

1. Call the balance query API using GET /v1/pay/balance/query with desired currencies
2. Store balances by currency in your merchant’s local accounting system
3. Compare with local records to identify discrepancies
4. Alert on thresholds if balance falls below operational minimums

​

Order Fee Query

​

Common Use Cases

• Financial reconciliation: Verify fees match merchant expectations
• Multiple or partial payments: Reconcile complex order scenarios
• Exception investigation: Identify fee anomalies or discrepancies
• Settlement confirmation: Confirm amounts before initiating payout

​

API Reference

​

Request Parameters

​

Response Fields

​

Example Request

curl -X GET "https://api.gatepay.io/api/open/v1/pay/order/fee/query?merchant_order_no=ORDER_12345" \
  -H "X-GatePay-Certificate-ClientId: your_client_id" \
  -H "X-GatePay-Timestamp: 1704067200000" \
  -H "X-GatePay-Nonce: abc123def456" \
  -H "X-GatePay-Signature: your_signature" \

​

Example Response

{
  "data": {
    "orderId": "ORD_abc123",
    "merchant_order_no": "ORDER_12345",
    "orderAmount": "1000.00",
    "payAmount": "1000.00",
    "settlementAmount": "980.00",
    "gatewayFee": "20.00",
    "networkFee": "0.00",
    "discountAmount": "0.00",
    "currency": "USDT",
    "status": "SETTLED",
    "created_at": 1704067200000,
    "settled_at": 1704067800000
  }
}

​

Integration Steps

1. Call the order fee query API using GET /api/open/v1/pay/order/fee/query with order identifier
2. Store the query result alongside your local order master data
3. Compare settlement amounts with expected values
4. Flag discrepancies for manual review if fee structure differs

​

Funds Ledger Query

​

Common Use Cases

• End-of-day reconciliation: Aggregate all fund movements for the day
• Audit tracing: Track fund origins and destinations for compliance
• Exception investigation: Identify timing issues or missing transactions
• Financial reporting: Generate detailed movement reports by type and currency

​

API Reference

​

Request Parameters

​

Response Fields

​

Transaction Type Enumeration

​

Example Request

curl -X GET "https://api.gatepay.io/v1/pay/bill/orderlist?start_time=1704067200000&end_time=1704153600000&limit=50" \
  -H "X-GatePay-Certificate-ClientId: your_client_id" \
  -H "X-GatePay-Timestamp: 1704067200000" \
  -H "X-GatePay-Nonce: abc123def456" \
  -H "X-GatePay-Signature: your_signature" \

​

Example Response

{
  "data": [
    {
      "ledger_id": "LED_20240101_001",
      "type": "PAYMENT",
      "currency": "USDT",
      "amount": "500.00",
      "balance_before": "10000.00",
      "balance_after": "10500.00",
      "business_id": "ORD_abc123",
      "description": "Payment from order ORDER_12345",
      "created_at": 1704067200000,
      "metadata": {
        "order_no": "ORDER_12345",
        "payer": "customer@example.com"
      }
    },
    {
      "ledger_id": "LED_20240101_002",
      "type": "REFUND",
      "currency": "USDT",
      "amount": "-100.00",
      "balance_before": "10500.00",
      "balance_after": "10400.00",
      "business_id": "REF_xyz789",
      "description": "Refund for order ORDER_12346",
      "created_at": 1704067800000,
      "metadata": {
        "order_no": "ORDER_12346",
        "reason": "Customer requested"
      }
    },
    {
      "ledger_id": "LED_20240101_003",
      "type": "TRANSFER_OUT",
      "currency": "USDT",
      "amount": "-1000.00",
      "balance_before": "10400.00",
      "balance_after": "9400.00",
      "business_id": "TRN_20240101",
      "description": "Transfer to sub-account",
      "created_at": 1704068400000,
      "metadata": {
        "account_id": "SUB_12345",
        "batch_no": "TRN_20240101"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 3,
    "has_next": false
  }
}

​

Integration Steps

1. Pull funds ledger records by time range with pagination using GET /v1/pay/bill/orderlist
2. Persist ledger records in your database using ledger_id as the primary deduplication key
3. Associate ledger records with business orders using business_id and metadata
4. Generate reconciliation summaries aggregated by:
   • Currency
   • Transaction type
   • Date or time bucket
   • Related business entity (order, refund, transfer, etc.)
5. Compare with local records to identify discrepancies
6. Flag unmatched records for investigation

​

Recommended End-of-Day Reconciliation Flow

​

Step 1: Capture Account Balance Snapshot

GET /v1/pay/balance/query

• Available balance
• Hold amount
• Total balance
• Snapshot timestamp

​

Step 2: Pull Funds Ledger Records

GET /v1/pay/bill/orderlist?start_time={start_of_day}&end_time={end_of_day}&limit=100

​

Step 3: Pull Order Fees and Settlement Amounts

GET /api/open/v1/pay/order/fee/query?merchant_order_no={order_id}

​

Step 4: Match and Reconcile Records

• Match PAYMENT ledger entries to your order system using business_id
• Match REFUND entries to your refund system
• Match TRANSFER_OUT/IN entries to your transfer records
• Match PAYOUT entries to your settlement records

​

Step 5: Generate Discrepancy Report

​

Step 6: Perform Manual Review

1. Review the ledger entry description and metadata
2. Correlate with business records (orders, refunds, transfers)
3. Investigate timing (same-day vs. next-day settlement)
4. Document resolution (matched, explained, or escalated)

​

Step 7: Output Reconciliation Result

End-of-Day Reconciliation Report
Date: 2024-01-01
Start Balance (USDT): 10,000.00
Ending Balance (USDT): 9,900.00

Transactions:
- Payments In: +5,000.00
- Refunds Out: -2,500.00
- Transfers Out: -1,000.00
- Fees Out: -500.00
- Adjustments: -100.00

Calculated Ending Balance: 9,900.00
Actual Ending Balance: 9,900.00
Status: BALANCED ✓

Discrepancies: 0
Unmatched Records: 0

​

Error Handling and Troubleshooting

​

Common Issues

​

Best Practices

​

Data Persistence

• Primary Key: Use ledger_id for ledger entries to ensure idempotency
• Unique Constraints: Enforce unique constraints on (ledger_id) to prevent duplicates
• Indexing: Index by (created_at, currency, type) for fast reconciliation queries

​

Query Optimization

• Time ranges: Query in 24-hour buckets for faster response times
• Pagination: Use limit=100 and iterate through pages to avoid timeout
• Filters: Use currency and type filters to reduce result sets

​

Alerting and Monitoring

• Threshold alerts: Alert when available balance falls below operational minimum
• Discrepancy alerts: Alert immediately when reconciliation identifies unmatched records
• Timing alerts: Alert if ledger entries are delayed by more than 2 hours
• Callback failure alerts: Alert if expected callbacks are not received within SLA

​

Documentation and Audit

• Reconciliation logs: Store reconciliation results with timestamp and user ID
• Discrepancy tracking: Maintain audit trail of identified and resolved discrepancies
• Rate cards: Document fee structure and any promotional adjustments
• Settlement terms: Document when and how funds are settled to merchant accounts

​

Related Documentation

• Authentication & Security
• Institution API
• Notification & Callbacks
• Error Codes & Best Practices
• Currency Conversion & Swap
• General Overview