API 参考

API 参考文档

所有接口的请求参数、响应格式与代码示例，助您快速完成对接。

快速开始 API 参考 SDK 下载 沙盒环境 状态监控
Base URL：https://api.degaoco.com/v1（生产）  |  https://sandbox-api.degaoco.com/v1（沙盒）

订单 API

POST /orders 创建支付订单

创建一笔新的支付订单，返回支付 URL 或收银台 H5 地址。

请求参数

参数类型必填说明
amountinteger必填订单金额，单位为分（分）
currencystring必填货币代码，如 CNY、USD
subjectstring必填商品名称，最长 128 字符
channelstring必填支付渠道：alipay / wechat / card / auto
out_trade_nostring必填商户订单号，全局唯一
notify_urlstring必填支付结果回调地址（HTTPS）
return_urlstring可选支付完成后跳转地址
bodystring可选订单详情描述，最长 512 字符
expire_timeinteger可选订单有效期（秒），默认 1800

请求示例

JSON · Request Body
{
  "amount": 9900,
  "currency": "CNY",
  "subject": "订单 #1001",
  "channel": "alipay",
  "out_trade_no": "YOUR_ORDER_123",
  "notify_url": "https://yoursite.com/webhook",
  "return_url": "https://yoursite.com/success"
}

响应示例

JSON · Response 200
{
  "id": "ord_8f2a91bc3e7d4f1a",
  "status": "pending",
  "amount": 9900,
  "currency": "CNY",
  "pay_url": "https://pay.degaoco.com/order/ord_8f2a91bc3e7d4f1a",
  "qr_code": "https://api.degaoco.com/qr/ord_...",
  "expire_at": 1710244800,
  "created_at": 1710243000
}
GET /orders/{id} 查询订单详情

通过订单 ID 查询订单详情及当前状态。

参数位置必填说明
idPath必填订单 ID（ord_ 开头）或商户订单号

Webhook 回调

支付完成后，得锆服务器将向您配置的 notify_url 发送 POST 请求通知。

验签说明：收到通知后必须验证 X-Degao-Signature 请求头中的签名，确认通知来自得锆服务器。
JSON · Webhook Body (支付成功)
{
  "event": "order.paid",
  "order_id": "ord_8f2a91bc3e7d4f1a",
  "out_trade_no": "YOUR_ORDER_123",
  "amount": 9900,
  "channel": "alipay",
  "channel_trade_no": "2024031222001414680501695647",
  "paid_at": 1710243120,
  "status": "paid"
}
回复规则：成功处理后请返回 HTTP 200 状态码，响应体包含 {"code":"success"}，否则得锆将在 24 小时内按退避算法重试最多 8 次。

错误码说明

错误码HTTP 状态说明
INVALID_PARAMS400请求参数校验失败，请检查必填字段格式
UNAUTHORIZED401鉴权失败，请检查 API Key 及签名是否正确
FORBIDDEN403无权限访问该资源，请确认账户状态
ORDER_NOT_FOUND404订单不存在，请确认订单 ID 是否正确
ORDER_ALREADY_PAID409订单已支付，不可重复付款
AMOUNT_EXCEED_LIMIT422单笔金额超出限额，请拆分订单或联系客服
CHANNEL_UNAVAILABLE503支付渠道暂时不可用，可切换渠道或稍后重试
INTERNAL_ERROR500得锆服务内部错误，请联系技术支持