Skip to main content

​
Overview

GatePay provides multiple payment collection methods to accommodate different merchant and user scenarios:
  • Hosted Checkout Payments: GatePay-managed payment UI supporting QR-code and on-chain dynamic address payments
  • Address Payments: Direct payment to dynamically generated or static collection addresses
  • Payment Launch: Mobile and client-side integration for in-app payment flows

​
Hosted Checkout Payments

​
Product Overview

Hosted checkout payment is a full-featured, GatePay-hosted collection capability. Merchants do not need to build their own payment user interface. GatePay handles both:
  • QR-code payments
  • On-chain dynamic address payments (Web3)

​
Payment Flow

The hosted checkout payment flow consists of three main steps:
  1. Pre-order Creation: The merchant creates a pre-order and receives redirect information from the API.
  2. User Redirection: The merchant redirects the user to the GatePay hosted checkout page using the provided location URL.
  3. Asynchronous Notification: After the user completes payment, GatePay asynchronously notifies the merchant backend of the order status via callback.
Important: The merchant must not construct the checkout URL manually. Always use the location value returned by the API.

​
Query Supported Chains

Request: 
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 Hosted Checkout Order

Request: 
POST /v1/pay/checkout/order
Creates a new hosted checkout order. 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.

​
Request Parameters

FieldTypeRequiredDescription
merchantTradeNostringYesUnique merchant order number for this transaction
currencystringYesOrder currency code (e.g., USDT, USD)
orderAmountstringYesOrder amount in the specified currency
callbackUrlstringYesMerchant endpoint URL to receive order status callbacks. See Notification Callbacks for details.
orderExpireTimenumberNoOrder expiration time (Unix timestamp in seconds). Default: 1 hour from creation.

​
Response Fields

FieldTypeDescription
prepayIdstringGatePay pre-order 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

Request: 
GET /v2/pay/order/query
Query the current status and details of an order. This endpoint is essential for payment confirmation and reconciliation.

​
Payment Amount Handling

The interpretation of payment amounts differs based on order type:
  • Gate Payments (non-address): The final paid amount is represented by orderAmount.
  • Address Payments: 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 merchant account

​
Signed Requests and Callbacks

For security details on request signing and callback verification, see Authentication and Security.

​
Address Payments

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

​
Typical Integration Flow

  1. Chain Query: Query supported chains for your order currency.
  2. Order Creation: Create an order; the system generates and returns a unique collection address.
  3. User Payment: User transfers funds to the collection address.
  4. Payment Detection: GatePay detects the on-chain transaction and notifies your backend via callback.
  5. Result Confirmation: Confirm payment via callbacks 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 merchant account after on-chain confirmation.
  • Immediate Crediting: Funds are credited immediately upon order creation (for supported scenarios).

​
Order Statuses

Common PAY_ADDRESS order statuses:
StatusDescription
PAY_SUCCESSPayment succeeded and funds are credited
PAY_ERRORPayment failed; funds were not credited
PAY_CLOSEOrder was closed by the merchant or system
PAY_EXPIRED_IN_PROCESSOrder validity period expired, but some on-chain transactions 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 orders, you may need to query supported conversion currencies.

​
Query Supported Conversion Currencies (Convert Mode Only)

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

​
Create Address Payment Order

Request: 
POST /v1/pay/address/create
Creates a new address payment order and generates a unique payment address.

​
Query Address Payment Order

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

​
Static Address Payments

Static address payment enables merchants to configure a fixed collection address for long-term or recurring payment scenarios. This is ideal for:
  • Subscription or recurring billing
  • Tip jars or fundraising pages
  • Merchant 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 orders without creating a new address each time.
  3. Automatic Detection: GatePay detects payments to the static address and sends notifications.
If a configuration already exists for the same channelId and chain, the API updates it.

​
Save or Update Static Address Configuration

Request: 
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 applications or client-side web applications. This flow allows users to initiate payments directly from your application without leaving the app.

​
Integration Steps

  1. Server-Side Pre-order: Create a pre-order on your backend using the checkout order endpoint.
  2. Client Launch: Pass the prepayId to your client application.
  3. Client Query: The client can optionally query the order status for UI updates.
  4. Parameter 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 Parameter Validation

Request: 
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-order Response Fields

When you create a pre-order for payment launch, the response includes:
FieldTypeDescription
prepayIdstringPre-order 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 application returns to your merchant 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 reconciliation

​
Payment Validity and Expiration

​
Default Validity Period

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

​
Delayed Payment Handling

If a blockchain transaction is submitted after the order’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 merchant account after on-chain confirmation, even though the order is expired.
  • Convert Delayed Payment: User funds do not enter the merchant payment account. The order is treated as failed.

​
Refunds

GatePay provides two refund APIs for backward compatibility: Request: 
POST /v2/pay/order/refund
Standard refund endpoint for new integrations. Use this for all new implementations.

​
Compatibility Refund (Legacy)

Request: 
POST /v1/pay/order/refund
Legacy refund endpoint. Maintained for existing integrations only. New integrations must use the v2 endpoint.

​
Callbacks and Asynchronous Notifications

All payment methods support asynchronous callbacks to notify your backend of order status changes. For complete callback details, payload schemas, signing, and verification, see Notification Callbacks. GatePay guarantees:
  • Callbacks are sent to the callbackUrl provided at order creation
  • Callbacks include signed payloads for security verification
  • Multiple callback attempts if the initial delivery fails

​
Best Practices

  1. Always Verify Callbacks: Use the signature provided with each callback for verification. See Authentication and Security.
  2. Use Query as Fallback: If callback delivery is delayed or missed, use the query endpoints for reconciliation.
  3. Handle Delayed Payments: Implement logic to handle payments that arrive after order expiration.
  4. Monitor Amount Fields: For address payments, always check both waitAmountOnChain and doneAmountOnChain to get the complete payment picture.
  5. Store prepayId: Keep the prepayId returned from order creation for tracking and support purposes.
  6. Implement Idempotency: Use unique merchantTradeNo values to prevent duplicate orders.