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

# Quickstart

> Run your first GatePay payment flow with the minimum path: signing, order creation, callback handling, and final query.

## Overview

This page provides a minimum runnable path for merchants who want to complete their first GatePay payment flow from end to end.

This document set focuses on the production integration flow. Before you begin integration, complete merchant onboarding, app creation, key setup, and callback URL configuration.

If this is your first integration, use the following order:

1. Obtain `ClientId` and signing secrets
2. Generate the signed request headers
3. Create your first checkout order
4. Receive and verify the asynchronous callback
5. Use the query endpoint for final confirmation

## Step 1: Prepare Credentials

After creating your application in the merchant console, prepare at least the following:

| Credential         | Purpose                                                  |
| ------------------ | -------------------------------------------------------- |
| `ClientId`         | Sent through the `X-GatePay-Certificate-ClientId` header |
| Payment API Secret | Used to sign payment-related requests                    |
| Callback URL       | Used to receive asynchronous notifications               |

If you have not completed this setup, see [Overview](/essentials/version/100/en/common/overview) and [Authentication](/essentials/version/100/en/common/authentication).

## Step 2: Build the Signed Headers

At minimum, GatePay request signing uses these headers:

* `X-GatePay-Certificate-ClientId`
* `X-GatePay-Timestamp`
* `X-GatePay-Nonce`
* `X-GatePay-Signature`

The core canonical string is:

```text theme={null}
timestamp\nnonce\nbody\n
```

Integration recommendations:

* use UTC milliseconds for `timestamp`
* use a one-time random string for `nonce`
* keep `body` exactly identical to the actual request payload
* log the canonical string locally before signing during integration debugging

### Python signing example

```python theme={null}
import hmac
import hashlib

timestamp = "1710000000000"
nonce = "abc123xyz789"
body = '{"merchantTradeNo":"M202604150001","currency":"USDT","orderAmount":"10.00"}'
secret = "your_payment_api_secret"

payload = f"{timestamp}\n{nonce}\n{body}\n"
signature = hmac.new(
    secret.encode("utf-8"),
    payload.encode("utf-8"),
    hashlib.sha512,
).hexdigest()

print(signature)
```

### Node.js signing example

```javascript theme={null}
const crypto = require("crypto");

const timestamp = "1710000000000";
const nonce = "abc123xyz789";
const body = '{"merchantTradeNo":"M202604150001","currency":"USDT","orderAmount":"10.00"}';
const secret = "your_payment_api_secret";

const payload = `${timestamp}\n${nonce}\n${body}\n`;
const signature = crypto
  .createHmac("sha512", secret)
  .update(payload, "utf8")
  .digest("hex");

console.log(signature);
```

For the full signing rules, see [Security and Signature](/api-reference/version/100/en/common/securityAndSignature).

## Step 3: Create Your First Payment Order

The hosted checkout flow is the fastest way to validate signing, order creation, callback handling, and order querying.

**Request**

```http theme={null}
POST /v1/pay/checkout/order
```

**Minimum request example**

Notes:

* Standard merchant API examples do not include `X-GatePay-On-Behalf-Of` in this temporary release.
* In production integration, populate this header according to your subject-attribution model and the endpoint definition.

```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: abc123xyz789" \
  -H "X-GatePay-Signature: generated_signature" \
  -d '{
    "merchantTradeNo": "M202604150001",
    "currency": "USDT",
    "orderAmount": "10.00",
    "goods": {
      "goodsName": "Demo Order",
      "goodsDetail": "First payment integration test"
    },
    "callbackUrl": "https://merchant.example.com/webhook/gatepay",
    "returnUrl": "https://merchant.example.com/result"
  }'
```

Use only the standard GatePay signed headers for ordinary merchant requests.

**Key response fields**

| Field       | Description                                 |
| ----------- | ------------------------------------------- |
| `prepayId`  | GatePay pre-order ID used for later queries |
| `location`  | Hosted checkout redirect URL                |
| `qrContent` | QR-content URL returned in some modes       |

After order creation, redirect the user with the returned `location` value directly. Do not construct the checkout page URL manually.

## Step 4: Receive the Callback

After the user completes payment, GatePay sends an asynchronous callback to your configured callback URL.

**Example callback**

```json theme={null}
{
  "bizType": "PAY",
  "bizId": "6948484859590",
  "bizStatus": "PAY_SUCCESS",
  "client_id": "your_client_id",
  "data": "{\"merchantTradeNo\":\"M202604150001\",\"orderAmount\":\"10.00\"}"
}
```

Your callback handler should at minimum:

1. verify the signature
2. apply idempotent business processing
3. update the local order state
4. return HTTP 200 with the agreed acknowledgement body

For the unified callback model, see [Notification](/essentials/version/100/en/common/notification).

## Step 5: Query for Final Confirmation

For payment flows, the recommended operating model is callbacks first and query as fallback.

**Request**

```http theme={null}
GET /v2/pay/order/query
```

**Minimum query example**

```bash theme={null}
curl -X GET "https://openplatform.gateapi.io/v2/pay/order/query?merchantTradeNo=M202604150001" \
  -H "X-GatePay-Certificate-ClientId: your_client_id" \
  -H "X-GatePay-Timestamp: 1710000005000" \
  -H "X-GatePay-Nonce: query123" \
  -H "X-GatePay-Signature: generated_signature" \
```

Treat these as two different integration signals:

* callbacks for real-time business progression
* queries for final confirmation and reconciliation

## Pre-Go-Live Checklist

* `ClientId`, secret, and callback URL are confirmed
* request signing and callback verification are implemented server-side
* `merchantTradeNo` and `prepayId` are persisted
* callback idempotency is implemented
* query endpoints are integrated as fallback
* monitoring and failure alerting are in place

## What to Read Next

* For the full collection flow, continue with [Payment](/essentials/version/100/en/inflow/payment/payment)
* For fiat settlement flows, continue with [OTC](/essentials/version/100/en/otc)
* For outbound merchant transfers, continue with [Payout](/essentials/version/100/en/outflow/payout)