订单号规则

订单号是用于跟踪Smilepayz支付系统中交易的唯一标识符。遵循正确的格式可确保成功的交易处理和正确的记录管理。

📋 要求

字符长度

• 最小: 6个字符
• 最大: 32个字符
• 推荐: 16-24个字符以获得最佳可读性

允许的字符

• 数字: 0-9
• 字母: A-Z、a-z（不区分大小写）
• 特殊字符: 不允许

唯一性

• 每个订单号在您的商户账户中必须是全局唯一的
• 重复的订单号将导致交易被拒绝
• 订单号不能在不同交易中重复使用

🚫 限制

• 不允许空格或特殊符号（例如：!@#$%^&*()）
• 不允许连字符或下划线
• 不允许Unicode或非ASCII字符
• 不能以系统使用的保留前缀开头

💡 最佳实践

推荐格式

[前缀][时间戳][随机字符]

示例: ORD20241201123456789ABC

命名约定

• 使用有意义的前缀（例如：PAY、ORD、TXN）
• 包含时间戳以便按时间顺序排列
• 添加随机字符以确保唯一性
• 在您的应用程序中保持一致的格式

📝 实现示例

{
  "merchantId": "sandbox-20001",
  "orderNo": "T37484Fx383ksd90383",
  "amount": 1000.00,
  "currency": "THB",
  "paymentMethod": "QRPAY"
}

{
  "merchantId": "20001",
  "orderNo": "37484Fx383ksd90383",
  "amount": 1000.00,
  "currency": "THB",
  "paymentMethod": "QRPAY"
}

⚠️ 常见错误

❌ 无效示例

"orderNo": "123"           // 太短（少于6个字符）
"orderNo": "ORDER-123"     // 包含连字符
"orderNo": "ORDER_123"     // 包含下划线
"orderNo": "ORDER@123"     // 包含特殊字符
"orderNo": "ORDER 123"     // 包含空格

✅ 有效示例

"orderNo": "ORDER123456"   // 有效格式
"orderNo": "TXN20241201123456789ABC"  // 带时间戳
"orderNo": "PAYMENT001"    // 简单格式
"orderNo": "1234567890ABCDEF"  // 字母数字组合

🔍 验证

系统会自动验证订单号，如果出现以下情况将返回错误：

• 长度少于6个或超过32个字符
• 包含无效字符
• 订单号在系统中已存在
• 格式违反任何指定规则

📊 错误响应

如果提供了无效的订单号，API将返回：

{
  "code": "INVALID_ORDER_NO",
  "message": "订单号格式无效或已存在",
  "data": null
}

---

注意: 始终为每笔交易生成唯一的订单号，以确保正确的跟踪并避免支付系统中的冲突。