创建订阅支付

POST

测试环境：

https://test-api.yondepay.com/v1/authorise

正式环境：

https://api.yondepay.com/v1/authorise

📡 请求头参数

参数名	类型	必填	说明	示例值
`Content-Type`	string	必填	请求内容类型，必须为application/json	application/json

📤 请求参数

参数名	类型	必填	说明	示例值
`merchant_id`	string	必填	商户ID	701001
`account_id`	string	必填	账户ID	701001010
`order_no`	string	必填	商户订单号	2024010112345678
`currency`	string	必填	货币代码	USD
`amount`	string	必填	支付金额	9.99
`website`	string	必填	网站域名(根域名)	example.com
`items`	string	必填	商品信息描述格式：商品名#,#商品编号#,#单价#,#数量#,#商品URL#,#商品ID（多商品用#;#分隔）详细说明请参考：商品信息格式说明	video#,#VIP001#,#19.99#,#1#,#https://example.com/vip#,#12345
`shopper_id`	string	必填	用户ID	12345
`shopper_email`	string	必填	用户邮箱	[email protected]
`shopper_ip`	string	必填	用户IP地址	192.168.1.1
`open3d`	string	必填	3D验证设置，固定为no3DS	no3DS
`shopper_phone`	string	必填	用户手机号（不带国家代码）	(463) 782-2525
`card`	string	必填	信用卡号	4111111111111111
`expiration_month`	string	必填	过期月份	12
`expiration_year`	string	必填	过期年份	2025
`security_code`	string	必填	CVV安全码	123
`first_name`	string	必填	持卡人名字	John
`last_name`	string	必填	持卡人姓氏	Doe
`notify_url`	string	必填	异步通知回调地址	https://yoursite.com/callback
`billing_country`	string	必填	账单国家代码	US
`billing_state`	string	必填	账单州/省份	California
`billing_city`	string	必填	账单城市	Los Angeles
`billing_address`	string	必填	账单地址	123 Main Street
`billing_postal_code`	string	必填	账单邮政编码	90210
`delivery_country`	string	必填	送货国家代码	US
`accept`	string	必填	接受的响应格式	application/json
`subscription`	object	必填	订阅信息对象	参考下方子参数
├─ `contract`	string	必填	固定为RECURRING	RECURRING
├─ `contract_name`	string	必填	合约名称	contract_name
├─ `interval`	string	必填	订阅周期类型 year month week	month
├─ `interval_count`	string	必填	固定为1	1
├─ `billing_cycle`	integer	必填	计费周期订阅的总计费周期数。例如，如果 billing_cycle=12、interval_count=1 且 interval=month 1 年。如果 billing_cycle 为 0，则订阅将无限期持续。	0
├─ `promotion_cycle`	integer	可选	促销周期促销周期数。促销活动必须提供折扣周期数，并与间隔关联例如：promotion_cycle=3, interval=month 表示折扣周期为 3 个月可以理解为首月（或promotion_cycle个月）优惠价，后续按正常价格计费	1
└─ `contract_amount`	string	必填	合约金额订阅标准价格，如果没有折扣计划（没有任何促销，这将是订阅交易的金额）例如：amount=9.99, promotion_cycle=1, interval=month, contract_amount=19.99 表示首月优惠价为9.99，后续按19.99计费	19.99
`encryption_data`	string	必填	SHA256签名数据用于确保请求完整性和真实性的签名哈希详细生成方法请参考：签名生成说明	64位十六进制字符串

🛍️ 商品信息格式说明 (items)

格式规范：商品信息必须按照固定顺序排列，各字段间用 #,# 分隔，多个商品用 #;# 分隔

单个商品格式：

商品名称#,#商品编号#,#单价#,#数量#,#商品URL#,#商品ID

多个商品格式：

商品1名称#,#商品1编号#,#商品1单价#,#商品1数量#,#商品1URL#,#商品1ID#;#商品2名称#,#商品2编号#,#商品2单价#,#商品2数量#,#商品2URL#,#商品2ID

字段说明：

字段位置	字段名称	说明	示例
1	商品名称	商品的名称描述	video
2	商品编号	商品的唯一编号，如为空使用"0"	VIP001
3	单价	商品单价，必须与订单货币一致	19.99
4	数量	商品数量	1
5	商品URL	商品详情页链接，如为空使用"0"	https://example.com/vip
6	商品ID	商品在系统中的ID，如为空使用"0"	12345

格式示例：

// 单个商品
"video#,#VIP001#,#19.99#,#1#,#https://example.com/vip#,#12345"

// 多个商品
"video#,#VIP001#,#19.99#,#1#,#https://example.com/vip#,#12345#;#高级功能包#,#FUNC001#,#4.99#,#2#,#https://example.com/func#,#67890"

// 部分字段为空的示例（用"0"替代）
"基础套餐#,#0#,#5.99#,#1#,#0#,#0"

重要提醒：

所有字段必须按顺序填写，不能省略
如果某个字段为空，必须用 "0" 替代
商品价格的货币的种类必须与订单中的 currency 字段一致
分隔符必须严格使用 #,# 和 #;#

🔐 签名生成说明 (encryption_data)

签名机制：HCPay使用SHA256算法对请求参数进行签名，确保数据传输的完整性和真实性

📋 签名字段顺序

签名字段必须按以下顺序拼接：

merchant_id + account_id + order_no + currency + amount + first_name + last_name + card + expiration_year + expiration_month + security_code + shopper_email + sign_key

🔑 签名密钥

重要说明：

每个商户账户都分配有唯一的签名密钥（sign_key）
测试环境和正式环境使用不同的签名密钥
签名密钥必须严格保密，不得在公开场所（如GitHub、客户端代码）中暴露

💻 PHP签名生成示例

<?php
// 签名参数（按官方文档顺序）
// 注意：所有参数值都不能含有空格
$merchant_id = '701001';
$account_id = '701001010';
$order_no = '2024010112345678';
$currency = 'USD';
$amount = '19.99';
$first_name = 'John';
$last_name = 'Doe';
$card = '4111111111111111';
$expiration_year = '2025';
$expiration_month = '12';
$security_code = '123';
$shopper_email = '[email protected]';
$sign_key = 'YOUR_SIGN_KEY'; // 从HCPay获取的签名密钥

// 按顺序拼接所有参数（参数间无分隔符，参数值无空格）
$sign_string = $merchant_id . $account_id . $order_no . $currency . $amount . 
               $first_name . $last_name . $card . $expiration_year . 
               $expiration_month . $security_code . $shopper_email . $sign_key;

// 生成SHA256签名
$encryption_data = hash('sha256', $sign_string);

echo "签名字符串: " . $sign_string . "\n";
echo "SHA256签名: " . $encryption_data;
?>

🔗 在线工具

您也可以使用在线SHA256生成工具进行测试验证。

签名验证要点：

所有参数必须按照官方文档规定的顺序拼接
参数值直接连接，中间不添加任何分隔符
⚠️ 重要：所有用于加密的参数值都不能含有空格
最终生成64位十六进制字符串
测试和生产环境必须使用对应的签名密钥
所有API请求必须通过HTTPS发送

📨 响应格式

✅ 成功响应

成功响应分为两种情况，根据 issuer_url 字段区分：

🔐 需要3DS验证 (有issuer_url字段)

说明：存在 issuer_url 字段时，表示需要进行3DS验证，客户需要跳转到 issuer_url 完成验证

重要：issuer_url 需要拼接 return_url 和 notify_url 参数后再进行跳转

URL拼接示例：

// 原始 issuer_url
https://api.star-saas.com/v1/Company3dRequest?order_no=2024010112345678&type=JP

// 拼接后的完整URL  
https://api.star-saas.com/v1/Company3dRequest?order_no=2024010112345678&type=JP&return_url=https://yoursite.com/return& notify_url=https://yoursite.com/callback

return_url: 3DS验证完成后的页面跳转地址
return_url: 3DS验证结果的异步通知地址

状态码：200 OK 格式：XML

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <merchant_id>701001</merchant_id>
    <account_id>701001010</account_id>
    <order_no>2024010112345678</order_no>
    <amount>19.99</amount>
    <currency>USD</currency>
    <transaction_id>JA579197925052</transaction_id>
    <return_type>0</return_type>
    <issuer_url>https://api.star-saas.com/v1/Company3dRequest?order_no=2024010112345678&type=JP</issuer_url>
    <jwt></jwt>
</response>

✅ 直接成功

状态码：200 OK 格式：XML

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <merchant_id>701001</merchant_id>
    <account_id>701001010</account_id>
    <order_no>2024010112345678</order_no>
    <amount>19.99</amount>
    <currency>USD</currency>
    <transaction_id>JAD428936742238</transaction_id>
    <return_type>2</return_type>
    <card>411111***1111</card>
    <order_status>1</order_status>
    <result_info>0000:Success</result_info>
    <encryption_data>3691464E6EB7F9330C22375079F00D9CB5768F44E66B442C396FB865074C6F5E</encryption_data>
    <note></note>
    <token_id>GMSxxr7qvB5YSTIH553Uk5t2WTGLXufB</token_id>
</response>

❌ 失败响应

状态码：400 Bad Request 格式：JSON

{
    "code": "CARD_DECLINED", 
    "message": "Card declined"
}

🔔 回调通知参数

支付完成后(或者3ds验证后)，系统会向商户提供的 notify_url 发送POST回调通知。

✅ 成功回调通知

成功回调通知分为两种类型：单笔支付成功和订阅支付成功

💰 单笔支付成功回调

说明：当单笔支付成功时，回调通知中不包含订阅相关字段

{
     "merchant_id": "701001",
     "account_id": "701001010",
     "transaction_id": "JAD428936742238",
     "order_no": "2024010112345678",
     "amount": "19.99",
     "currency": "USD",
     "order_status": 1,
     "result_info": "00:Approved",
     "encryption_data": "3691464E6EB7F9330C22375079F00D9CB5768F44E66B442C396FB865074C6F5E",
     "note": "",
     "return_type": 3,
     "webhooks_type": "PAYMENT",
     "next_step_solutions": "",
     "card_scheme": "Visa",
     "payment_method": "Credit Card",
     "card": "411111***1111",
     "threeds_result": "",
     "billing_address": "123 Main Street"
 }

🔄 订阅支付成功回调

说明：当订阅支付成功时，回调通知中会包含 recurring_id 等订阅相关字段

重要标识：存在 recurring_id 参数才算是订阅成功

{
     "merchant_id": "701001",
     "account_id": "701001010",
     "transaction_id": "JAD428936742238",
     "order_no": "2024010112345678",
     "amount": "19.99",
     "currency": "USD",
     "order_status": 1,
     "result_info": "0000:Success",
     "encryption_data": "B65DAD56479DF6E5DAF16211D733163E71BCB06768C18481B02AEF73E88DDB86",
     "note": "",
     "return_type": 3,
     "webhooks_type": "PAYMENT",
     "recurring_id": "198c0df8-2100-4725-8ab1-d0d1ea06dd02",
     "recurring_deduction_period": 1,
     "recurring_deduction_time": "2025-01-20",
     "contract_name": "user:12345_monthlyVIP",
     "recurring_status": 1,
     "card_scheme": "Visa",
     "payment_method": "Credit Card",
     "card": "411111***1111",
     "threeds_result": "",
     "billing_address": "123 Main Street",
     "token_id": "2wWGGbyTUeVCo9rtTKnozCYXlAEh3unP"
 }

❌ 失败回调通知

说明：当支付失败时，会收到以下回调通知参数

{
     "merchant_id": "701001",
     "account_id": "701001010",
     "transaction_id": "JA433900760006",
     "order_no": "2024010112345678",
     "amount": "19.99",
     "currency": "USD",
     "order_status": 0,
     "result_info": "Card declined",
     "encryption_data": "75C64F06B78609B381912740CFF26A82D7CAF35E5CCAADBE7E9AD427C2178212",
     "note": "",
     "return_type": 3,
     "webhooks_type": "PAYMENT",
     "next_step_solutions": "",
     "card_scheme": "Visa",
     "payment_method": "Credit Card",
     "card": "411111***1111",
     "threeds_result": "",
     "billing_address": "123 Main Street"
 }

📊 回调通知字段说明

字段名	说明	单笔支付	订阅支付	失败时
`return_type`	返回类型： 1: Real-time response from the browser 2: Real-time response from the server 3: Asynchronous response from the server	✓	✓	✓
`order_status`	订单状态：1-成功，0-失败	✓	✓	✓
`result_info`	结果信息	✓	✓	✓
`encryption_data`	签名数据	✓	✓	✓
`amount`	支付金额	✓	✓	✓
`currency`	货币代码	✓	✓	✓
`merchant_id`	商户ID	✓	✓	✓
`account_id`	账户ID	✓	✓	✓
`transaction_id`	交易ID	✓	✓	✓
`order_no`	商户订单号	✓	✓	✓
`card_scheme`	卡组织	✓	✓	✓
`payment_method`	支付方式	✓	✓	✓
`card`	脱敏卡号	✓	✓	✓
`webhooks_type`	回调类型	✓	✓	✓
`billing_address`	账单地址	✓	✓	✓
`next_step_solutions`	下一步解决方案	✓	✓	✓
`recurring_id`	订阅ID（订阅成功的关键标识）	-	✓	-
`recurring_deduction_period`	订阅扣费周期	-	✓	-
`recurring_deduction_time`	当前扣费日期	-	✓	-
`contract_name`	合约名称	-	✓	-
`recurring_status`	订阅/扣费状态： 0: Creation failed -1: Pending 1: Creation successful 2: Deduction failed 3: Deduction successful 4: Final deduction failed	-	✓	-
`token_id`	卡token（用于后续扣费）	-	✓	-

回调处理要求：

收到回调通知后，必须返回 success 字符串确认接收
如未返回确认，系统将按重试策略重新发送通知
建议验证 encryption_data 签名确保数据完整性
根据 order_status 字段判断支付结果：1-成功，0-失败
订阅识别：存在 recurring_id 参数才算是订阅成功

💻 调用示例

curl -X POST "https://test-api.yondepay.com/v1/authorise" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "701001",
    "account_id": "701001010",
    "order_no": "2024010112345678",
    "currency": "USD",
    "amount": "19.99",
    "website": "example.com",
    "items": "video#,#VIP001#,#19.99#,#1#,#https://example.com/vip#,#12345",
    "shopper_id": 12345,
    "shopper_email": "[email protected]",
    "shopper_ip": "192.168.1.1",
    "open3d": "no3DS",
    "shopper_phone": "123456",
    "card": "4111111111111111",
    "expiration_month": "12",
    "expiration_year": "2025",
    "security_code": "123",
    "first_name": "John",
    "last_name": "Doe",
    "notify_url": "https://yoursite.com/callback",
    "billing_country": "US",
    "billing_state": "California",
    "billing_city": "Los Angeles",
    "billing_address": "123 Main Street",
    "billing_postal_code": "90210",
    "delivery_country": "US",
    "accept": "application/json",
    "subscription": {
      "contract": "RECURRING",
      "contract_name": "user:12345_monthlyVIP",
      "interval": "monthly",
      "interval_count": 1,
      "billing_cycle": 0,
      "promotion_cycle": 1,
      "contract_amount": "19.99"
    },
    "encryption_data": "your_signature"
  }'