API Reference · Stable v1

PQAPI Payment API

Base URL：https://shop.pqapi.shop。正式接入以本页面和 /openapi.yaml 为接口契约。

Authentication

所有私有端点要求 HMAC-SHA256 鉴权。

X-Site-Id: YOUR_SITE_ID
X-Timestamp: 1787150000
X-Nonce: f640886a1ad24cb1
X-Signature: <64 lowercase hex chars>

Canonical string：

timestamp + "\n" + nonce + "\n" + raw_json_body

GET 请求的 raw body 为空字符串。POST 请求必须对实际发送的原始 JSON 字符串签名。

Create Checkout Session

POST/api/v1/checkout-sessions

Request

{
  "merchant_order_no": "ORDER202608200001",
  "amount": 289900,
  "currency": "CNY",
  "description": "Order payment"
}

201 Response

{
  "ok": true,
  "checkout": {
    "payment_order_no": "PAY202608200001ABC12345",
    "merchant_order_no": "ORDER202608200001",
    "amount": 289900,
    "currency": "CNY",
    "description": "Order payment",
    "status": "CREATED",
    "checkout_url": "https://shop.pqapi.shop/pay/...",
    "created_at": "2026-08-20T00:10:00+08:00",
    "expires_at": "2026-08-20T00:40:00+08:00",
    "paid_at": null
  }
}

cURL

curl -X POST 'https://shop.pqapi.shop/api/v1/checkout-sessions' \
  -H 'Content-Type: application/json' \
  -H 'X-Site-Id: YOUR_SITE_ID' \
  -H 'X-Timestamp: 1787150000' \
  -H 'X-Nonce: f640886a1ad24cb1' \
  -H 'X-Signature: <signature>' \
  --data-raw '{"merchant_order_no":"ORDER202608200001","amount":289900,"currency":"CNY","description":"Order payment"}'

同一 site_id + merchant_order_no 重试时，如果金额与币种一致，会返回原有支付单；冲突则返回 409 idempotency_conflict。

Retrieve Checkout Session

GET/api/v1/checkout-sessions/{payment_order_no}

按 PQAPI 支付单号读取最终状态、Provider、交易号和支付时间。

Retrieve Merchant Order

GET/api/v1/orders/{merchant_order_no}

按 A 站自己的业务订单号查询。

Supported Currencies

GET/api/v1/config/currencies

公开接口，当前返回 CNY、USD、HKD，minor unit 均为 2。

Webhook

支付成功确认后，PQAPI 会向站点配置的 Webhook URL 发送 payment.paid。

X-Site-Id: YOUR_SITE_ID
X-Event-Id: evt_...
X-Timestamp: 1787150000
X-Signature: <signature>

Webhook canonical：

timestamp + "\n" + event_id + "\n" + raw_webhook_body

Webhook 文档 OpenAPI 3.1

Common Errors

HTTP	error	说明
401	signature_invalid	签名不正确
409	replay_detected	Nonce 已使用
409	idempotency_conflict	相同订单号金额或币种冲突
404	order_not_found	订单不存在
422	amount_invalid	金额非法

查看完整错误码 →