Quickstart - Gate Pay DOCS

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:

Obtain ClientId and signing secrets
Generate the signed request headers
Create your first checkout order
Receive and verify the asynchronous callback
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 and 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:

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

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

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.

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

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.

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

{
  "bizType": "PAY",
  "bizId": "6948484859590",
  "bizStatus": "PAY_SUCCESS",
  "client_id": "your_client_id",
  "data": "{\"merchantTradeNo\":\"M202604150001\",\"orderAmount\":\"10.00\"}"
}

Your callback handler should at minimum:

verify the signature
apply idempotent business processing
update the local order state
return HTTP 200 with the agreed acknowledgement body

For the unified callback model, see Notification.

Step 5: Query for Final Confirmation

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

GET /v2/pay/order/query

Minimum query example

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

Documentation Index

​Overview

​Step 1: Prepare Credentials

​Step 2: Build the Signed Headers

​Python signing example

​Node.js signing example

​Step 3: Create Your First Payment Order

​Step 4: Receive the Callback

​Step 5: Query for Final Confirmation

​Pre-Go-Live Checklist

​What to Read Next