创建交易

接口信息

POST /payment/{apiKey}/transaction

• 路径参数：apiKey（商户 API Key）
• 频率限制：60次 / 60秒

支付模式

paymentType	说明	是否需要 cardInfo
PAY	直连信用卡支付	是
CHECKOUT	收银台模式，用户在页面填卡	否
SUBSCRIPTION	订阅扣费（首次）	是

请求参数

顶层参数

参数名	类型	长度	必填	参与签名	说明
requestId	String	100	是	是	请求ID，保证幂等性
relationId	String	200	是	是	关联ID，必须唯一
paymentType	String	200	是	是	PAY / CHECKOUT / SUBSCRIPTION
planId	String	200	条件必填	是	订阅计划ID（SUBSCRIPTION 时必填）
userId	String	200	条件必填	是	用户ID（SUBSCRIPTION 时必填）
payAmount	String	(12,2)	是	是	支付金额，保留两位小数
currency	String	200	是	是	货币（ISO），如 USD
clientIp	String	100	是	是	客户端 IP
returnUrl	String	500	是	是	支付成功跳转地址
failedUrl	String	500	是	是	支付失败跳转地址
cancelUrl	String	500	是	是	支付取消跳转地址
notifyUrl	String	500	是	是	回调地址（优先级高于商户配置）
billingAddress	String	text	是	否	账单地址（JSON 字符串）
shippingAddress	String	text	是	否	物流地址（JSON 字符串）
cardInfo	String	text	条件必填	是	信用卡信息（PAY/SUBSCRIPTION 必填）
items	String	text	是	是	商品信息（JSON 数组字符串）
merchantId	String	200	是	是	商户号
sign	String	text	是	否	签名（本字段不参与签名计算）

cardInfo 字段

PAY 和 SUBSCRIPTION 模式必传，整体序列化为 JSON 字符串后作为 cardInfo 传入

字段	类型	必填	说明
holderName	String	是	持卡人姓名
cardNumber	String	是	卡号
month	String	是	月份（两位，如 11）
year	String	是	年份（四位，如 2027）
cvv	String	是	卡背面 CVV

billingAddress / shippingAddress 字段

字段	类型	必填	说明
firstName	String	是	名
lastName	String	是	姓
country	String	是	国家 Code（ISO）
state	String	是	州 Code（ISO）
province	String	是	区 Code（ISO）
city	String	是	城市
street	String	是	街道
address	String	是	详细地址
postalCode	String	是	邮编
phone	String	是	电话
email	String	是	邮箱
countryName	String	否	国家名称
provinceName	String	否	区名称
number	String	否	门牌号
areaCode	String	否	区号
birthDate	String	否	生日（yyyy/MM/dd）
identityNumber	String	否	证件号码

items 字段（数组）

字段	类型	必填	说明
name	String	是	商品名称（不含特殊字符、表情、中文）
price	String	是	SKU 价格
num	String	是	SKU 数量
currency	String	是	货币
sku	String	是	SKU 名称
url	String	是	SKU 链接
category	String	否	类目信息

响应参数

字段	类型	说明
data.transactionOrderId	String	交易订单 ID
data.relationId	String	关联 ID
data.subscriptionId	String	订阅 ID（仅订阅支付返回）
data.subscriptionCode	String	订阅编号（仅订阅支付返回）
data.status	String	订单状态，见状态码说明
data.payAmount	String	支付金额
data.currency	String	货币
data.txnAmount	String	结算金额
data.txnCurrency	String	结算货币
data.url	String	需跳转时的 URL（3DS 验证/收银台）
data.createTime	String	创建时间
data.txnTime	String	结算时间
data.merchantId	String	商户号

请求示例

{
  "requestId": "REQ_20241021_001",
  "relationId": "39d9663d889929d962dd8999",
  "paymentType": "PAY",
  "merchantId": "888888888",
  "payAmount": "299",
  "currency": "USD",
  "clientIp": "153.12.187.15",
  "returnUrl": "https://www.yoursite.com/success",
  "failedUrl": "https://www.yoursite.com/failed",
  "cancelUrl": "https://www.yoursite.com/cancel",
  "notifyUrl": "https://www.yoursite.com/webhook/payment",
  "billingAddress": "{\"firstName\":\"John\",\"lastName\":\"Doe\",\"country\":\"US\",\"state\":\"CA\",\"city\":\"Los Angeles\",\"address\":\"123 Main St\",\"postalCode\":\"90001\",\"phone\":\"+12345678901\",\"email\":\"[email protected]\"}",
  "shippingAddress": "{\"firstName\":\"John\",\"lastName\":\"Doe\",\"country\":\"US\",\"state\":\"CA\",\"city\":\"Los Angeles\",\"address\":\"123 Main St\",\"postalCode\":\"90001\",\"phone\":\"+12345678901\",\"email\":\"[email protected]\"}",
  "cardInfo": "{\"holderName\":\"John Doe\",\"cardNumber\":\"4000000000000000\",\"month\":\"11\",\"year\":\"2027\",\"cvv\":\"123\"}",
  "items": "[{\"name\":\"Product Name\",\"price\":\"299\",\"num\":\"1\",\"currency\":\"USD\",\"sku\":\"SKU_001\",\"url\":\"https://yoursite.com/product/001\"}]",
  "sign": "5097d223b249d4512a6103ce06568f2ddbfff8716c14c8465be1e543b842dc4e"
}

响应示例

成功（直接扣款）

{
  "rtn_code": "0000",
  "success": true,
  "data": {
    "transactionOrderId": "300068705107664897",
    "relationId": "39d9663d889929d962dd8999",
    "status": "100000",
    "payAmount": "299",
    "currency": "USD",
    "merchantId": "888888888",
    "createTime": "2024-05-27 10:43:18"
  }
}

需要 3DS 验证

{
  "rtn_code": "0000",
  "success": true,
  "data": {
    "transactionOrderId": "300068705107664897",
    "relationId": "39d9663d889929d962dd8999",
    "status": "100040",
    "payAmount": "299",
    "currency": "USD",
    "merchantId": "888888888",
    "createTime": "2024-05-27 10:43:18",
    "url": "https://testthreeds.codrimpay.com/threeds2.html?tradeCode=T300068704444964864"
  }
}

NOTE

status=100040 时，需要引导用户跳转到 data.url 完成 3DS 验证。 支付最终结果以 Webhook 回调为准，status=100000 只代表渠道接受了请求。

接口别名

POST /v1/{apiKey}/transaction

与主路径功能完全等价，使用相同的签名验证逻辑。