Overview
GatePay payouts enable merchants to distribute funds to multiple recipients in a single batch operation. Common use cases include:- Commission distribution to affiliates or partners
- Merchant settlement and revenue sharing
- Batch fund transfers to user wallets
- Royalty payments
- Refunds and chargebacks
Prerequisites
Before integrating payout capabilities, you must complete the following setup steps:- Application Creation: Create a GatePay application in the merchant dashboard
- Client ID Retrieval: Obtain your
ClientIdfor API authentication - Signing Key Configuration: Configure your signing key for request authentication
- Callback URL Configuration: Set up your callback endpoint for asynchronous notifications
Payout Integration Steps
Step 1: Query Fees and Limits
Before creating any payout batch, query the current fee structure and amount limits. These values may change dynamically and should not be cached. Request:- Current withdrawal fees
- Minimum and maximum payout amounts
- Per-transaction limits
- Daily payout limits
Step 2: Create a Batch Payout
Create a batch containing one or more sub-orders (recipient withdrawal requests). Each batch is identified by a uniquebatch_id.
Step 3: Receive Callbacks and Track Status
GatePay sends asynchronous callbacks to your configured callback URL. These callbacks report both batch-level status and individual sub-order status. Callback Order:- Initial callback when batch is created (
INITstatus) - Processing callback when batch enters processing (
PROCESSINGstatus) - Final callback with completion status (
SUCCESS,PARTIAL, orFAIL)
Step 4: Reconciliation and Fallback Queries
Use the query API as a fallback mechanism for:- Verifying callback delivery
- Reconciling accounts
- Investigating failed transactions
- Confirming final status
Callbacks First, Query as Fallback
GatePay’s payout system prioritizes asynchronous callbacks for reliability and performance:| Stage | Primary Method | Fallback |
|---|---|---|
| Batch Status | Receive callbacks to callbackUrl | Use POST /v1/pay/withdraw/query to query batch status |
| Sub-order Status | Callbacks include sub-order details | Query individual sub-order details via query API |
| Reconciliation | Receive detailed callback payloads with all amounts and fees | Query endpoint for audit trails and confirmation |
Idempotency and Reconciliation
GatePay uses two key identifiers for idempotency and reconciliation:| Field | Scope | Purpose | Usage |
|---|---|---|---|
merchant_withdraw_id | Per sub-order | Merchant-assigned unique identifier for each withdrawal recipient | Idempotency; prevent duplicate payouts to the same recipient |
suborder_id | Per sub-order | GatePay-assigned unique identifier | Platform-side tracking, callbacks, and query operations |
merchant_withdraw_id values, GatePay will detect duplicates and prevent double-payments.
Batch and Sub-Order Statuses
Batch Status Lifecycle
A batch progresses through the following states:| Status | Description |
|---|---|
INIT | Batch created; initial validation in progress |
PROCESSING | Batch being processed; funds are being transferred on-chain |
PARTIAL | Some sub-orders succeeded; others failed |
FAIL | Entire batch failed; no funds were distributed |
SUCCESS | Entire batch succeeded; all sub-orders completed |
Sub-Order Status
Each withdrawal within a batch has its own status:| Status | Description |
|---|---|
DONE | Sub-order completed successfully; funds transferred and confirmed |
FAIL | Sub-order failed; funds were not transferred or were reversed |
Callback Payload Structure
Main Batch Callback Payload
When a batch status changes, GatePay sends a callback with the following main-order fields:| Field | Required | Description |
|---|---|---|
batch_id | Yes | Unique batch identifier assigned by GatePay |
merchant_id | Yes | Your merchant ID from GatePay |
status | Yes | Current batch status: INIT, PROCESSING, PARTIAL, FAIL, or SUCCESS |
client_id | Yes | The client_id used to create this batch |
pay_back_status | Yes | Rollback/refund status for the batch |
channel_id | Yes | Channel identifier used for this payout batch |
Sub-Order Array Callback Payload
Each callback includes asuborders array with detailed information about individual withdrawals:
| Field | Required | Description |
|---|---|---|
suborder_id | Yes | GatePay-assigned sub-order identifier |
chain | Yes | Blockchain network (e.g., Ethereum, Polygon) |
address | Yes | Recipient wallet address |
currency | Yes | Payout currency (e.g., USDT, ETH) |
amount | Yes | Requested payout amount in currency units |
fee | Yes | Actual fee deducted for this sub-order |
txHash | Yes | Blockchain transaction hash (confirms on-chain transfer) |
status | Yes | Sub-order status: DONE or FAIL |
merchant_withdraw_id | Yes | Your merchant-assigned identifier for reconciliation |
fee_type | Yes | Fee deduction type: 0 (internal) or 1 (external) |
finish_time | Yes | Completion timestamp (Unix epoch in seconds) |
sub_amount | Yes | Total amount for this sub-order (including fee if applicable) |
done_amount | Yes | Amount actually credited to the recipient’s address |
Fee Type Clarification
- Fee Type 0 (Internal Deduction): Fee is deducted from the merchant’s account; the full
amountis sent to the recipient. - Fee Type 1 (External Deduction): Fee is deducted from the withdrawal amount; the recipient receives
amount - fee.
Error Handling
Common Error Codes
When creating or processing payouts, you may encounter the following error codes:| Error Code | Description | Applicable API | Recommended Handling |
|---|---|---|---|
550233 | Insufficient balance in merchant account | Batch payout creation | Check available balance via account balance query; top up account |
550234 | Memo/description field exceeds maximum length | Batch payout creation | Check memo length limits and truncate if necessary |
550235 | Amount precision exceeds allowed decimal places | Batch payout creation | Verify amount precision matches currency requirements (e.g., USDT typically allows 6 decimals) |
550238 | Batch contains too many sub-orders | Batch payout creation | Split into multiple batches with fewer sub-orders |
550239 | amount field is missing or empty | Batch payout creation | Verify amount is provided for each sub-order |
550240 | currency field is missing or empty | Batch payout creation | Verify currency is provided for each sub-order |
550241 | address field is missing or empty | Batch payout creation | Verify recipient address is provided for each sub-order |
550242 | chain field is missing or empty | Batch payout creation | Verify blockchain network is provided for each sub-order |
550245 | batch_id already exists (duplicate batch) | Batch payout creation | Use a unique batch_id or leverage idempotency for retries |
550249 | Invalid batch_id or merchant_withdraw_id format | Batch payout creation | Ensure IDs are valid strings without special characters |
Error Response Handling
When an error occurs, GatePay returns an error response with:- Error Code: Numeric identifier for the error
- Error Message: Human-readable description
- Details: Additional context (if available)
Reconciliation and Auditing
Account Balance Reconciliation
Regularly reconcile your GatePay merchant account balance against your internal records:- Query Fees Before Each Payout: Get current fee rates
- Track Batch Status: Monitor batch and sub-order status via callbacks
- Audit Amounts: Verify
amount,fee, anddone_amountmatch your expectations - Reconcile Daily: Use query APIs to reconcile at end of day
Investigating Failed Payouts
If a sub-order fails:- Check Sub-Order Status: Query the batch to get
statusfor each sub-order - Review Error Details: Look for error reason in callback or query response
- Verify Recipient Address: Ensure wallet address is valid for the specified chain
- Check Recipient Chain: Confirm the recipient’s wallet supports the specified blockchain
- Retry If Transient: For temporary failures, resubmit with a new
batch_idand samemerchant_withdraw_id
Query Payout Results
Request:- Batch status and metadata
- Sub-order array with individual results
- Fee information
- Transaction hashes for on-chain verification
- Fallback verification if callbacks are delayed
- Periodic reconciliation
- Detailed audit trails
- Support and investigation
Request Signing and Validation
All payout requests must be signed using your configured signing key. For details on request signing, signature generation, and signature verification for callbacks, see Authentication and Security. Key signing requirements:- Sign the request body with your private key
- Include the signature in the
X-Signatureheader - Verify callback signatures using your public key
Best Practices
- Query Fees Dynamically: Always query current fees before creating a batch; do not cache fee values.
- Use Unique Identifiers: Assign unique
merchant_withdraw_idandbatch_idvalues to prevent duplicates and enable idempotency. - Implement Callback Handling: Set up robust callback processing for real-time status updates.
- Monitor Batch Status: Track batches through their lifecycle; alert on
PARTIALorFAILstatus. - Verify Transactions On-Chain: For critical payouts, verify
txHashon the blockchain explorer. - Reconcile Daily: Reconcile your internal account balance against GatePay records daily.
- Handle Errors Gracefully: Implement proper error handling with exponential backoff for retries.
- Secure Your Signing Key: Protect your signing key; never expose it in logs or to unauthorized parties.
- Validate Recipient Addresses: Perform basic validation (checksum, format) on recipient addresses before submission.
- Plan for Rate Limits: Be aware of API rate limits; implement request queuing for large batch operations.