账户余额

​

概述

• 余额查询：按币种返回实时可用余额
• 订单手续费查询：按订单核验手续费和结算金额
• 资金流水查询：按交易跟踪所有资金变动

​

余额查询

​

常见使用场景

• 结算前校验：发起结算前确认可用余额
• 期末余额快照：在营业结束时记录余额，用于会计核对
• 运营监控：实时余额告警与阈值监控
• Multi-currency management: Track balances across different currencies

​

API 参考

​

请求 参数

​

响应 字段

​

Example 请求

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 响应

{
  "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 步骤

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

​

订单手续费查询

​

常见使用场景

• Financial 对账: Verify fees match 商户 expectations
• Multiple or partial payments: Reconcile complex 订单 scenarios
• Exception investigation: Identify fee anomalies or discrepancies
• Settlement confirmation: Confirm amounts before initiating 出款

​

API 参考

​

请求 参数

​

响应 字段

​

Example 请求

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 响应

{
  "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 步骤

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

​

资金流水查询

​

常见使用场景

• End-of-day 对账: Aggregate all 资金 movements for the day
• Audit tracing: Track 资金 origins and destinations for compliance
• Exception investigation: Identify timing issues or missing 交易s
• Financial reporting: Generate detailed movement reports by type and currency

​

API 参考

​

请求 参数

​

响应 字段

​

Transaction 类型 Enumeration

​

Example 请求

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 响应

{
  "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 步骤

1. Pull 资金 账本 records by time range with pagination using GET /v1/pay/bill/orderlist
2. Persist 账本 records in your database using ledger_id as the primary deduplication key
3. Associate 账本 records with business 订单s using business_id and metadata
4. Generate 对账 summaries aggregated by:
   • 币种
   • Transaction type
   • Date or time bucket
   • Related business entity (订单, re资金, transfer, etc.)
5. Compare with local records to identify discrepancies
6. Flag unmatched records for investigation

​

Recommended End-of-Day 对账 Flow

​

步骤 1: Capture Account Balance Snapshot

GET /v1/pay/balance/query

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

​

步骤 2: Pull Funds Ledger Records

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

​

步骤 3: Pull Order Fees and Settlement Amounts

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

​

步骤 4: Match and Reconcile Records

• Match PAYMENT 账本 entries to your 订单 system using business_id
• Match REFUND entries to your re资金 system
• Match TRANSFER_OUT/IN entries to your transfer records
• Match PAYOUT entries to your settlement records

​

步骤 5: Generate Discrepancy Report

​

步骤 6: Perform Manual Review

1. Review the 账本 entry description and metadata
2. Correlate with business records (订单s, re资金, transfers)
3. Investigate timing (same-day vs. next-day settlement)
4. Document resolution (matched, explained, or escalated)

​

步骤 7: Output 对账 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 处理方式 and Troubleshooting

​

Common Issues

​

最佳实践

​

Data Persistence

• Primary Key: Use ledger_id for 账本 entries to ensure 幂等性
• Unique Constraints: Enforce unique constraints on (账本_id) to prevent duplicates
• Indexing: Index by (created_at, currency, type) for fast 对账 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 对账 identifies unmatched records
• Timing alerts: Alert if 账本 entries are delayed by more than 2 hours
• 回调 failure alerts: Alert if expected 回调s are not received within SLA

​

Documentation and Audit

• 对账 logs: Store 对账 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 资金 are settled to 商户 accounts

​

Related Documentation

• 认证与安全
• 机构 API
• 通知 & 回调
• 错误码s & 最佳实践
• 币种 Conversion & Swap
• 接入总览