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

The exact request body depends on the collection mode and the capabilities enabled for your account. In practice, checkout requests often combine several categories of information:
  • order identity, amount, and currency
  • user or terminal context
  • goods or display information
  • redirect or notification settings when supported by the specific API
  • chain and asset-related fields for crypto payment scenarios
If this is your first integration, the safest approach is to implement against the corresponding API Reference page and OpenAPI schema directly instead of relying on a shortened parameter summary from the guide.

​
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)

​
Minimum Runnable Example

If your goal is to get the first payment flow working quickly, the example below is more useful than treating the guide as a complete field reference. Create order 
curl -X POST "https://openplatform.gateapi.io/v1/pay/checkout/order" \
  -H "Content-Type: application/json" \
  -H "X-GatePay-Certificate-ClientId: your_client_id" \
  -H "X-GatePay-Timestamp: 1710000000000" \
  -H "X-GatePay-Nonce: checkout001" \
  -H "X-GatePay-Signature: generated_signature" \
  -d '{
    "merchantTradeNo": "M202604150001",
    "currency": "USDT",
    "orderAmount": "10.00",
    "goods": {
      "goodsName": "Demo Order",
      "goodsDetail": "Checkout quickstart"
    },
    "callbackUrl": "https://merchant.example.com/webhook/gatepay",
    "returnUrl": "https://merchant.example.com/result"
  }'
Typical success-response focus
  • persist prepayId
  • read location
  • redirect the user with location
Recommended next steps
  1. wait for the PAY callback
  2. call GET /v2/pay/order/query for final confirmation
  3. persist both merchantTradeNo and prepayId for reconciliation

​
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. It is best to treat this endpoint as the final confirmation source for payment results, not only as an exception-handling tool. Even after a successful callback has been received, merchants can still use this query for reconciliation or high-value order confirmation.

​
Query Entry by Payment Method

  • Hosted checkout payment: GET /v2/pay/order/query
  • Address payment: GET /v1/pay/address/query
  • QR / web-launch payment: use the actual query endpoint exposed by the corresponding API Reference page for that product flow
Do not mix query endpoints across different product lines. Even where field names look similar, status semantics, amount interpretation, and supplemental fields may differ.

​
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 Order: The system will generate and return a unique receiving address. If the TON network is used, a Memo field will also be returned (to prevent asset loss, users must include the Memo when making the payment).
  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.

​
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
The system will generate and return a unique receiving address. If the TON network is used, a Memo field will also be returned (to prevent asset loss, users must include the Memo when making the payment). When switching between non-convert and convert modes, make sure your team aligns on how payment currency, settlement currency, and callback fields should be interpreted. This avoids mixing business meanings across two different settlement models.

​
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 supports merchants in configuring fixed receiving addresses for long-term or recurring payment scenarios. If the TON network is used, a Memo field will also be returned (to prevent asset loss, users must include the Memo when making the payment). Applicable scenarios include:
  • Subscription or recurring billing
  • Tip jars or fundraising pages
  • Merchant settlement accounts
  • Commission distribution

​
How It Works

  1. Configure Static Address: Use the save API to configure a fixed receiving address for a specified channel and blockchain. If the TON network is used, a Memo field will also be returned (to prevent asset loss, users must include the Memo when making the payment).
  2. Reuse Address: Reuse the same address and Memo (if applicable) across multiple orders without generating 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. Be careful to distinguish between:
  • API-initiated refunds: integrate according to the endpoint and callback model described in this documentation
  • Merchant-console manual refunds: progress visibility is based on the merchant console and should not be assumed to follow the same API callback cadence

​
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. GatePay guarantees:
  • Callbacks are sent according to the callback configuration or callback parameter defined for the specific order flow
  • Callbacks include signed payloads for security verification
  • Multiple callback attempts if the initial delivery fails
For payment integrations, a reliable operating pattern is to use callbacks to advance the business workflow and use order queries as the final fallback and reconciliation source. If you prefer to start from a complete end-to-end flow instead of reading product sections one by one, see Quickstart.

​
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.