跳转到主要内容

​
概述

GatePay 提供多种收款方式，以适配不同的商户和用户场景：
  • 托管收银台支付：由 GatePay 托管支付界面，支持二维码支付和链上动态地址支付
  • 地址支付：直接向动态生成或静态收款地址发起付款
  • 支付拉起：适用于移动端和客户端的应用内支付拉起场景

​
托管收银台支付

​
产品概述

托管收银台支付是由 GatePay 提供的完整收款能力。商户无需自行建设支付页面，GatePay 会统一处理以下方式：
  • 二维码支付
  • 链上动态地址支付（Web3）

​
支付流程

The hosted checkout payment flow consists of three main steps:
  1. Pre-订单 Creation: The 商户 creates a pre-订单 and receives redirect information from the API.
  2. User Redirection: The 商户 redirects the user to the GatePay hosted checkout page using the provided location URL.
  3. Asynchronous 通知: After the user completes payment, GatePay 异步ly notifies the 商户 backend of the 订单 status via 回调.
Important: The 商户 must not construct the checkout URL manually. Always use the location value returned by the API.

​
Query Supported Chains

请求: 
GET /v1/pay/address/chains
Query the list of supported blockchain networks for Web3 address payments. This endpoint helps you determine which chains are available for your payment currency.

​
Create 托管收银台 Order

请求: 
POST /v1/pay/checkout/order
Creates a new hosted checkout 订单. Upon success, the API returns a location field that you must use to redirect the user. This URL is the only valid entry point to the GatePay hosted checkout page.

​
请求 参数

字段类型必填说明
merchantTradeNostringYesUnique 商户 订单 number for this 交易
currencystringYesOrder currency code (e.g., USDT, USD)
orderAmountstringYesOrder amount in the specified currency
callbackUrlstringYes商户 endpoint URL to receive 订单 status 回调. See 通知 回调 for details.
orderExpireTimenumberNoOrder expiration time (Unix timestamp in seconds). Default: 1 hour from creation.

​
响应 字段

字段类型说明
prepayIdstringGatePay pre-订单 ID for tracking and queries
locationstringHosted checkout redirect URL. Redirect the user to this URL.
qrContentstringQR code content for QR-based payment (if applicable)

​
Query Order Result

请求: 
GET /v2/pay/order/query
Query the current status and details of an 订单. This endpoint is essential for payment confirmation and 对账.

​
Payment Amount 处理方式

The interpretation of payment amounts differs based on 订单 type:
  • Gate 支付 (non-address): The final paid amount is represented by orderAmount.
  • Address 支付: Both waitAmountOnChain and doneAmountOnChain must be considered:
    • waitAmountOnChain: On-chain amount already detected but not yet finally confirmed
    • doneAmountOnChain: On-chain amount already confirmed and credited to the 商户 account

​
Signed 请求 and 回调

For security details on request signing and 回调 verification, see 认证与安全.

​
Address 支付

Address payments enable direct collection to blockchain addresses. The system dynamically generates payment addresses based on 订单 parameters or uses pre-configured static addresses.

​
Typical Integration Flow

  1. Chain Query: Query supported chains for your 订单 currency.
  2. Order Creation: Create an 订单; the system generates and returns a unique collection address.
  3. User Payment: User transfers 资金 to the collection address.
  4. Payment Detection: GatePay detects the on-chain 交易 and notifies your backend via 回调.
  5. Result Confirmation: Confirm payment via 回调 or use the query API as a fallback.

​
Address Payment Credit Modes

GatePay supports two crediting modes for address payments:
  • Asynchronous Crediting: Funds are credited to the 商户 account after on-chain confirmation.
  • Immediate Crediting: Funds are credited immediately upon 订单 creation (for supported scenarios).

​
Order 状态

Common PAY_ADDRESS 订单 statuses:
状态说明
PAY_SUCCESSPayment succeeded and 资金 are credited
PAY_ERRORPayment failed; 资金 were not credited
PAY_CLOSEOrder was closed by the 商户 or system
PAY_EXPIRED_IN_PROCESSOrder validity period expired, but some on-chain 交易s remain unconfirmed. Funds may still be credited after confirmation.

​
Payment Mode Selection: Non-Convert vs. Convert

Non-Convert Mode: Funds are credited in the original payment currency. Convert Mode: Funds are converted to a different currency before crediting. For convert mode 订单s, you may need to query supported conversion currencies.

​
Query Supported Conversion 币种 (Convert Mode Only)

请求: 
GET /v1/pay/address/supportedconvertcurrencies
Lists currencies that support automatic conversion for address payments.

​
Create Address Payment Order

请求: 
POST /v1/pay/address/create
Creates a new address payment 订单 and generates a unique payment address.

​
Query Address Payment Order

请求: 
GET /v1/pay/address/query
Query the current status of an address payment 订单, including on-chain detection results and confirmation status.

​
Static Address 支付

Static address payment enables 商户s to configure a fixed collection address for long-term or recurring payment scenarios. This is ideal for:
  • Subscription or recurring billing
  • Tip jars or 资金raising pages
  • 商户 settlement accounts
  • Commission distribution

​
How It Works

  1. Configure Static Address: Use the save endpoint to configure a fixed collection address for a specific channel and blockchain.
  2. Reuse Address: Use the same address across multiple 订单s without creating a new address each time.
  3. Automatic Detection: GatePay detects payments to the static address and sends 通知.
If a configuration already exists for the same channelId and chain, the API updates it.

​
Save or Update Static Address Configuration

请求: 
POST /v1/pay/fixedaddress/save
Saves or updates a static address configuration for a specified channelId and blockchain network (chain).

​
Payment Launch

Payment launch enables in-app payment experiences for mobile 应用s or 客户端 web 应用s. This flow allows users to initiate payments directly from your 应用 without leaving the app.

​
Integration 步骤

  1. Server-Side Pre-订单: Create a pre-订单 on your backend using the checkout 订单 endpoint.
  2. Client Launch: Pass the prepayId to your client 应用.
  3. Client Query: The client can optionally query the 订单 status for UI updates.
  4. 参数 Validation: Validate payment parameters before launching the payment flow.
  5. Final Confirmation: After the user returns, confirm payment status via server-side query.

​
Client SDK 参数 Validation

请求: 
POST /v1/pay/open/sdk
Validates payment parameters and prepares the SDK for payment launch. Use this endpoint to validate prepayId and other parameters before initiating the client payment flow.

​
Server-Side Pre-订单 响应 字段

When you create a pre-订单 for payment launch, the response includes:
字段类型说明
prepayIdstringPre-订单 ID to pass to the client SDK
locationstringRedirect URL (used for web-based payment launch)
qrContentstringQR code content (optional, for QR-based flows)

​
Client Return and Payment Confirmation

Critical: After the client 应用 returns to your 商户 page, the redirect result or client status must NOT be treated as the final payment result. Always confirm payment status through a server-side query to GET /v2/pay/order/query. This ensures:
  • Accurate payment state in your system
  • Proper handling of pending or delayed payments
  • Fraud detection and 对账

​
Payment Validity and Expiration

​
Default Validity Period

By default, an 订单 remains valid for 1 hour from creation time. This is configurable via the orderExpireTime parameter.

​
Delayed Payment 处理方式

If a blockchain 交易 is submitted after the 订单’s expiration time, the payment is classified as a delayed payment. GatePay supports two handling modes:
  • Non-Convert Delayed Payment: Funds are still credited to the 商户 account after on-chain confirmation, even though the 订单 is expired.
  • Convert Delayed Payment: User 资金 do not enter the 商户 支付账户. The 订单 is treated as failed.

​
Re资金

GatePay provides two re资金 APIs for backward compatibility: 请求: 
POST /v2/pay/order/refund
Standard re资金 endpoint for new integrations. Use this for all new implementations.

​
Compatibility Re资金 (Legacy)

请求: 
POST /v1/pay/order/refund
Legacy re资金 endpoint. Maintained for existing integrations only. New integrations must use the v2 endpoint.

​
回调 and Asynchronous 通知

All payment methods support 异步 回调 to notify your backend of 订单 status changes. For complete 回调 details, payload schemas, signing, and verification, see 通知 回调. GatePay guarantees:
  • 回调 are sent to the callbackUrl provided at 订单 creation
  • 回调 include signed payloads for security verification
  • Multiple 回调 attempts if the initial delivery fails

​
最佳实践

  1. Always Verify 回调: Use the signature provided with each 回调 for verification. See 认证与安全.
  2. Use Query as Fallback: If 回调 delivery is delayed or missed, use the query endpoints for 对账.
  3. Handle Delayed 支付: Implement logic to handle payments that arrive after 订单 expiration.
  4. Monitor Amount 字段: For address payments, always check both waitAmountOnChain and doneAmountOnChain to get the complete payment picture.
  5. Store prepayId: Keep the prepayId returned from 订单 creation for tracking and support purposes.
  6. Implement Idempotency: Use unique merchantTradeNo values to prevent duplicate 订单.