跳到主要内容

创建订单

API 说明​

统一下单接口用于商户创建订单。

其他说明​

我们提供了两种创建订单的方式：

  1. 商户服务端签名创建订单，本文档介绍此方式。
  2. 使用 webui 组件，由支付组件进行服务端签名创建订单。具体请参考演示页面。

接口信息​

  • 接口 URL: POST /v2/createOrder
  • Content-Type: application/json
  • 认证: 需要在 Header 中传递 app-id 和签名验证

请求头参数​

参数类型是否必需描述
app-idstring是商户应用 ID
Content-Typestring是application/json

请求参数​

参数类型是否必需描述
payChannelstring是支付渠道名称
signstring是请求签名
outTradeNostring是商户订单号，必须唯一
amountstring是支付金额
currencystring是货币类型
currencyIdstring是货币 ID
timestampstring否时间戳
timeExpirestring否订单过期时间
payAddressstring否支付地址（settlement 通道必须传递此参数以支持退款）
extraobject否扩展参数，详见下文

请求数据结构​

以下是创建订单请求的Go结构体定义：

type CreateOrderRequest struct { 
	PayChannel string                 `json:"payChannel" form:"payChannel"` 
	Sign       string                 `json:"sign" form:"sign" binding:"required"` 
	OutTradeNo string                 `json:"outTradeNo" form:"outTradeNo" binding:"required"` 
	Amount     string                 `json:"amount" form:"amount" binding:"required"` 
	Currency   string                 `json:"currency" form:"currency"` 
	CurrencyId string                 `json:"currencyId"  form:"currencyId" ` 
	Timestamp  string                 `json:"timestamp" form:"timestamp"` 
	TimeExpire string                 `json:"timeExpire" form:"timeExpire"` 
	PayAddress string                 `json:"payAddress" form:"payAddress"` 
	Extra      map[string]interface{} `json:"extra" form:"extra"` 
}

扩展参数说明​

参数类型是否必需默认值描述
descriptionstring否"buy something"订单描述
attachstring否"chainpay-support"支付描述信息
channel_pay_typestring否"qrcode"支付类型，选项："qrcode"、"cards"

响应参数​

成功响应​

{
    "code": 0,
    "data": {
        "extra": {
            "abapay_deeplink": "",
            "paymentURL": "",
            "qrimage": "",
            "qrstring": ""
        },
        "orderNo": "1754377439308531400",
        "qrcode": "",
        "scheme": ""
    },
    "msg": "success"
}

错误响应​

{
    "code": 7,
    "data": {},
    "msg": "payment processing failed: "
}

请求示例​

cURL 示例​

curl -X POST "/v2/createOrder" \
  -H "Content-Type: application/json" \
  -H "app-id: your-app-id" \
  -d '{
    "payChannel": "demo",
    "sign": "generated_signature",
    "outTradeNo": "ORDER_20240101_001",
    "amount": "100.00",
    "currency": "USDT",
    "currencyId": "USDT",
    "timestamp": "1704067200",
    "timeExpire": "1704070800",
    "payAddress": "0x1234567890abcdef",
    "extra": {
      "channel_pay_type": "qrcode",
      "description": "buy something",
      "attach": "chainpay-support"
    }
  }'

银行卡支付订单示例​

请求参数​

{
    "payChannel": "payway",
    "sign": "generated_signature",
    "outTradeNo": "ORDER_20240101_001",
    "amount": "100.00",
    "currency": "USDT",
    "currencyId": "USDT",
    "timestamp": "1704067200",
    "timeExpire": "1704070800",
    "payAddress": "0x1234567890abcdef",
    "extra": {
      "channel_pay_type": "cards",
      "description": "buy something",
      "attach": "chainpay-support"
    }
}

响应参数​

{
    "code": 0,
    "data": {
        "extra": {
            "data": {
                "additional_params": "",
                "amount": "20.00",
                "cancel_url": "",
                "continue_success_url": "",
                "currency": "USD",
                "custom_fields": "",
                "description": "buy something",
                "email": "",
                "firstname": "",
                "google_pay_token": "",
                "hash": "dbBRKH+Tud7qhQRMWGU9bvtwqx2yPQccSXX34lXOxVWJlSqzE8k1xEg3RwpBwnKYtfM+q9OPWVknPxpl9WEjHQ==",
                "items": "",
                "lastname": "",
                "lifetime": "",
                "merchant_id": "ec000262",
                "payment_gate": "0",
                "payment_option": "cards",
                "payout": "",
                "phone": "",
                "req_time": "20250806055806",
                "return_deeplink": "",
                "return_params": "",
                "return_url": "",
                "shipping": "",
                "skip_success_page": "1",
                "tran_id": "1754459886204383900",
                "type": "purchase",
                "view_type": ""
            },
            "requestUrl": "https://checkout-sandbox.payway.com.kh/api/payment-gateway/v1/payments/purchase"
        },
        "orderNo": "1754459886204383900",
        "qrcode": "",
        "scheme": ""
    },
    "msg": "success"
}

备注​

您需要通过 POST 请求将返回的 requestUrl 和 extra 中的 data 参数提交到 requestUrl。表单提交后，您将被重定向到支付页面。 或者，您也可以使用 iframe 将支付页面嵌入到您的网页中。

订单回调​

支付完成后，商户需要配置回调地址以接收支付通知。

创建订单30秒后，ChainPay 将通过 POST 请求将订单信息发送到商户配置的回调地址。

通知策略：

  • 通知失败后重试
  • 重试间隔递增（0秒、10秒、20秒...）
  • 最多重试10次
  • 任何通知成功（返回"success"）时停止通知

回调请求参数​

回调请求参数是一个JSON对象。

{
    "appId": "merchant_app_id",
    "outTradeNo": "merchant_order_123",
    "attach": "custom_data",
    "nonce": "random_nonce",
    "hash": "tx_hash_123",
    "transactionId": "platform_tx_123",
    "status": "DONE_PAYMENT",
    "timestamp": "1683123456",
    "sign": "generated_signature"
}

回调参数说明​

参数类型是否必需默认值描述
appIdstring是商户应用ID
outTradeNostring是商户订单号
attachstring否自定义数据
noncestring是随机字符串
hashstring是交易哈希
transactionIdstring是平台交易ID
statusstring是支付状态
timestampstring是时间戳
signstring是签名

签名说明​

签名方式与创建订单签名相同。

  • 使用商户私钥进行签名
  • 接收后，商户需要使用公钥验证签名

签名验证​

商户需要使用公钥验证签名，确保其正确性。