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

# Payment

> This guide introduces GatePay's core collection products, including hosted checkout payments, address payments, static-address payments, and client-side payment launch flows.

## 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

| Field       | Type   | Description                                                  |
| ----------- | ------ | ------------------------------------------------------------ |
| `prepayId`  | string | GatePay pre-order ID for tracking and queries                |
| `location`  | string | Hosted checkout redirect URL. Redirect the user to this URL. |
| `qrContent` | string | QR 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**

```bash theme={null}
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](/essentials/version/100/en/common/authentication).

***

## 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:

| Status                   | Description                                                                                                                       |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `PAY_SUCCESS`            | Payment succeeded and funds are credited                                                                                          |
| `PAY_ERROR`              | Payment failed; funds were not credited                                                                                           |
| `PAY_CLOSE`              | Order was closed by the merchant or system                                                                                        |
| `PAY_EXPIRED_IN_PROCESS` | Order 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:

| Field       | Type   | Description                                      |
| ----------- | ------ | ------------------------------------------------ |
| `prepayId`  | string | Pre-order ID to pass to the client SDK           |
| `location`  | string | Redirect URL (used for web-based payment launch) |
| `qrContent` | string | QR 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:

### Standard Refund (Recommended)

**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](/essentials/version/100/en/common/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](/essentials/version/100/en/common/quickstart).

***

## Best Practices

1. **Always Verify Callbacks**: Use the signature provided with each callback for verification. See [Authentication and Security](/essentials/version/100/en/common/authentication).
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.

***

## Related Documentation

* [Notification](/essentials/version/100/en/common/notification)
* [Authentication and Security](/essentials/version/100/en/common/authentication)
* [Overview](/essentials/version/100/en/common/overview)
* [Quickstart](/essentials/version/100/en/common/quickstart)