# 建立 GMPay 訂單 

**POST**`https://pay.example.com/payments/gmpay/v1/order/create-transaction`

[請求範例 ↓](https://epusdt.com/zh-tw/api/endpoints/create-order#request-example)

在商戶伺服器上簽章，建立訂單後引導買家開啟 `payment_url`。`token` 與 `network` 必須同時傳入，也可同時省略，讓買家在收銀台選擇。

## 請求參數 

| 欄位            | 型別     | 必填   | 說明                                                                                                                            |
| ------------- | ------ | ---- | ----------------------------------------------------------------------------------------------------------------------------- |
| pid           | string | 是    | 商戶 PID，用於查詢 API Key，並參與簽名。                                                                                                    |
| order\_id     | string | 是    | 商戶訂單號，最長 32 字元，不能重複。                                                                                                          |
| currency      | string | 是    | 法幣幣種，如 cny、usd。                                                                                                               |
| token         | string | 條件必填 | 收款幣種，如 usdt、trx、usdc、sol。GMPay 可與 network 同時省略以建立狀態 4 佔位訂單。                                                                   |
| network       | string | 條件必填 | 收款網路，如 tron、solana、ethereum、binance、polygon、plasma。GMPay 可與 token 同時省略以建立狀態 4 佔位訂單。                                           |
| amount        | number | 是    | 法幣金額，必須大於 0.01。                                                                                                               |
| notify\_url   | string | 是    | 支付成功非同步回撥地址。                                                                                                                  |
| redirect\_url | string | 否    | 支付完成後的同步跳轉地址。                                                                                                                 |
| name          | string | 否    | 商品/訂單名稱。                                                                                                                      |
| payment\_type | string | 否    | GMPay 相容欄位，不要求必須傳；如果傳了非空值，必須參與 GMPay signature 計算。普通 GMPay 不傳時後臺會存為 Gmpay；傳 Epay（大小寫不敏感）會統一存為 Epay 並使用 EPay 回撥格式，且 PID 必須是數字。 |
| signature     | string | 是    | 64 位小寫十六進位制 GMPay HMAC-SHA256 簽名。                                                                                             |

範例使用示範金鑰 `epusdt_secret_key` 簽章。變更參數或商戶金鑰後，請在伺服器重新簽章。

## 相關文件 

* [開啟收銀台](https://epusdt.com/zh-tw/api/endpoints/open-checkout)
* [簽章規則](https://epusdt.com/zh-tw/api/payment#signing)

## 回應

application/json回應欄位
* `status_code` integer  
業務結果碼，可用於判斷原因。
* `message` string  
供閱讀的結果說明。
* `data` object  
介面回傳的資料，失敗時為 null。

  * `trade_id` string
  * `order_id` string
  * `status` integer
  * `expiration_time` integer
  * `payment_url` string
* `request_id` string  
可用於追蹤記錄的請求識別碼。

application/json回應欄位
* `status_code` integer  
業務結果碼，可用於判斷原因。
* `message` string  
供閱讀的結果說明。
* `data` null  
介面回傳的資料，失敗時為 null。
* `request_id` string  
可用於追蹤記錄的請求識別碼。

application/json回應欄位
* `status_code` integer  
業務結果碼，可用於判斷原因。
* `message` string  
供閱讀的結果說明。
* `data` null  
介面回傳的資料，失敗時為 null。
* `request_id` string  
可用於追蹤記錄的請求識別碼。

application/json回應欄位
* `status_code` integer  
業務結果碼，可用於判斷原因。
* `message` string  
供閱讀的結果說明。
* `data` null  
介面回傳的資料，失敗時為 null。
* `request_id` string  
可用於追蹤記錄的請求識別碼。

application/json回應欄位
* `status_code` integer  
業務結果碼，可用於判斷原因。
* `message` string  
供閱讀的結果說明。
* `data` null  
介面回傳的資料，失敗時為 null。
* `request_id` string  
可用於追蹤記錄的請求識別碼。

application/json回應欄位
* `status_code` integer  
業務結果碼，可用於判斷原因。
* `message` string  
供閱讀的結果說明。
* `data` null  
介面回傳的資料，失敗時為 null。
* `request_id` string  
可用於追蹤記錄的請求識別碼。

application/json回應欄位
* `status_code` integer  
業務結果碼，可用於判斷原因。
* `message` string  
供閱讀的結果說明。
* `data` null  
介面回傳的資料，失敗時為 null。
* `request_id` string  
可用於追蹤記錄的請求識別碼。

application/json回應欄位
* `status_code` integer  
業務結果碼，可用於判斷原因。
* `message` string  
供閱讀的結果說明。
* `data` null  
介面回傳的資料，失敗時為 null。
* `request_id` string  
可用於追蹤記錄的請求識別碼。

application/json回應欄位
* `status_code` integer  
業務結果碼，可用於判斷原因。
* `message` string  
供閱讀的結果說明。
* `data` null  
介面回傳的資料，失敗時為 null。
* `request_id` string  
可用於追蹤記錄的請求識別碼。

application/json回應欄位
* `status_code` integer  
業務結果碼，可用於判斷原因。
* `message` string  
供閱讀的結果說明。
* `data` null  
介面回傳的資料，失敗時為 null。
* `request_id` string  
可用於追蹤記錄的請求識別碼。

[error-codes.json ↓](https://epusdt.com/agent-setup/error-codes.json)

**請求範例**

閘道網址 

```
curl -i -X POST \
  'https://pay.example.com/payments/gmpay/v1/order/create-transaction' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "pid": "1000",
  "order_id": "ORD202605230001",
  "currency": "cny",
  "token": "usdt",
  "network": "tron",
  "amount": 100,
  "notify_url": "https://merchant.example/notify",
  "redirect_url": "https://merchant.example/return",
  "name": "VIP",
  "signature": "6f874b1919d95081835e2809b620e354a5866f5a6dbb2e432d1627f1eb10059d"
}'
```

**回應範例**200 · 成功401 · 簽名認證錯誤400 · 10009 · 無法解析引數400 · 10041 · 通知地址無效400 · 10002 · 支付交易已存在，請勿重複建立400 · 10004 · 支付金額有誤，無法滿足最小支付單位400 · 10014 · 鏈未啟用400 · 10016 · 支援的資產不存在400 · 10003 · 無可用錢包地址，無法發起支付400 · 10005 · 無可用金額通道

application/json · 回應欄位節選

```
{
  "status_code": 200,
  "message": "success",
  "data": {
    "trade_id": "20260523171652123456001",
    "order_id": "ORD202605230001",
    "status": 1,
    "expiration_time": 1779530812,
    "payment_url": "https://pay.example.com/pay/checkout-counter/20260523171652123456001"
  },
  "request_id": "b1344d70-ff19-4543-b601-37abfb3b3686"
}
```
