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
Gate Pay’s reconciliation capability allows merchants to batch-pull order details via API within a specified time range. Additional order list query types and fund flow query capabilities will be added incrementally.
Common use cases include:
- End-of-day reconciliation of Gate Pay collection and payout data against internal ledgers
- Integration with BI or data warehouses for scheduled order detail synchronization
- Filtering by order number and status to investigate individual or batch anomalies
- Serving as a fallback data source for payment/payout callbacks to confirm final status
Prerequisites
Before integrating reconciliation capabilities, complete the following preparation steps:
- Create an Application: Create a GatePay application in the merchant backend
- Obtain ClientId: Retrieve the ClientId used for API authentication
- Configure Signing Key: Set up the key required for request signing
- Configure Callback URL: Set the callback endpoint for receiving asynchronous notifications
For detailed configuration instructions, refer to Integration Overview and Authentication & Security.
Reconciliation Integration Steps
Step 1: Pull Collection Order List
Query collection orders paginated by creation time range, with filtering support by order type, status, payment method, etc.
Request Endpoint:
GET /payment/open/v1/pay/order/list
Step 2: Pull Payout Order List
Query payout orders paginated by creation time range, with filtering support by channel, order status, approval status, etc.
Request Endpoint:
GET /withdraw/open/v1/withdraw/suborder/query
Step 3: Reconcile with Internal Systems
Compare the order data pulled in the previous two steps with the merchant’s internal ledger, business systems, or financial records as needed to confirm data consistency. The specific reconciliation dimensions and process are defined by the merchant based on their own business requirements.
Step 4: Fallback Query
List queries can serve as a fallback mechanism to verify complete callback delivery, investigate discrepancies, or trace historical data. It is recommended to use callback processing and list pulling as complementary approaches rather than relying solely on one.
Order Status
Collection Order Status
Common status values for collection orders:
| Status | API Enum Value | Description |
|---|
| Pending Payment | WAIT_PAY | Order created, payment not yet completed |
| Processing | PAYING | Payment processing |
| Payment Successful | PAY_SUCCESS | Payment completed, eligible for credit reconciliation |
| Payment Failed | PAY_FAIL | Payment unsuccessful |
| Expired | EXPIRED | Exceeded valid payment time |
| Cancelled | CANCELLED | Order cancelled |
Payout Order Status
Common status values for payout orders:
| Status | API Enum Value | Description |
|---|
| Created | CREATED | Order created |
| Pending | PENDING | Awaiting processing |
| Under Review | UNDER_REVIEW | In approval workflow |
| Processing | PROCESSING | Funds being processed |
| Payout Successful | PAYOUT_SUCCESS | Payout completed, eligible for debit reconciliation |
| Payout Failed | PAYOUT_FAIL | Payout unsuccessful or reversed |
Error Handling
The following typical issues may be encountered when querying lists:
| Scenario | Description | Recommended Handling |
|---|
| Invalid Time Range | endTime / end_time is earlier than the start time, or the span exceeds limits | Split windows by day or hour; comply with span limits in the API Reference |
| Pagination Parameter Error | count missing or exceeds maximum | Set a reasonable count, use page to paginate through large ranges |
| Status Filter Mismatch | status passed does not belong to the current order type enumeration | Cross-reference the “Order Status” section and API Reference enum table |
| Authentication Failure | Signature error or Key lacks query permissions | Check Payment API Secret, X-GatePay-Signature, and Key permission scope |
| Data Volume Too Large | Single response timeout or rate limit triggered | Reduce time window, lower concurrency, schedule during off-peak hours if necessary |
Reconciliation & Audit
End-of-Day Reconciliation Process
It is recommended to regularly reconcile Gate Pay order data with internal system records:
- Define the Reconciliation Window: Set
startTime / endTime (collection) or start_time / end_time (payout) by business day
- Page Through List: Call the collection and payout list endpoints respectively until there are no more pages
- Verify Amount Fields: Confirm that amounts, fees, and settlement/received amounts match internal expectations
- Verify Final States: Confirm that the number of final-state orders is consistent with callback processing records
- Retain Discrepancy Records: Orders that cannot be automatically matched enter the manual review queue
Discrepancy Investigation
If an order is inconsistent with internal records, investigate using the following steps:
- Confirm Correlation Keys: Verify that
merchantTradeNo and orderId (collection), or merchantWithdrawId and suborderId (payout), correspond to the same transaction
- Check Order Status: Confirm whether it is in an intermediate state (e.g.,
PAYING, PROCESSING)
- Verify Refunds and Partial Success: Check
refund_amount or payout failure reasons
- On-Chain Evidence: In Web3 scenarios, use
hashes / txId for secondary confirmation on a block explorer
- Fallback Single Query: If necessary, call the single order detail endpoint or Merchant MCP tools for additional fields
Request Signing & Verification
All reconciliation requests must be signed using the Gate Pay unified signing mechanism:
- Use the Payment API Secret to compute HMAC-SHA512 on the request body following the
timestamp\nnonce\nbody\n pattern
- Place the signature result in the request header
X-GatePay-Signature
For details on request signing and signature generation, refer to the Authentication & Security documentation.
Best Practices
- Split Pulls by Window: For large time ranges, make batched requests by day or hour to avoid excessive data volume per request
- Dual-Channel Verification: Use callbacks for real-time status and list endpoints for end-of-day fallback
- Unified Reconciliation Keys: Establish fixed mapping rules for
merchantTradeNo / merchantWithdrawId in internal systems
- Retain Raw Responses: Keep raw API JSON from reconciliation tasks for audit and replay purposes
- Monitor Intermediate State Accumulation: Set alerts for orders that remain in
PAYING or PROCESSING for extended periods
- On-Chain Cross-Verification: Use
hashes / txId for secondary confirmation of critical Web3 transactions
- Daily Reconciliation: Complete the previous day’s full reconciliation by T+1 end of day
- Protect Signing Keys: Payment API Secret must not appear in logs or be exposed to unauthorized personnel
- Monitor Rate Limits: Control concurrency and request frequency during large-scale batch pulling
- Discrepancy Resolution Loop: Establish manual review and supplementary order processes for records that cannot be automatically matched
