创建二维码支付

根据商户系统的 10 位客户 ID 创建二维码支付及托管收银台链接。客户不存在时会在当前商户范围内自动创建。

external_customer_id 必须为 10 位数字，allow_multiple_deposits 必填。创建请求还必须携带 Idempotency-Key。

POST /api/v1/customer-deposits

200

{
  "deposit_session_id": "<string>",
  "customer_id": "<string>",
  "status": "active",
  "allow_multiple_deposits": true,
  "expires_at": 123,
  "url": "<string>",
  "metadata": {},
  "created": 123
}

授权

Authorization · string · header · 必填

Bearer API Key，例如 Bearer sk_live_xxx。

X-StablePay-Timestamp · string · header · 必填

Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。

X-StablePay-Nonce · string · header · 必填

防重放随机字符串，长度 16-64 个字符。

X-StablePay-Signature · string · header · 必填

使用商户 API Secret 计算的 HMAC-SHA256 小写 hex 签名。

请求头

X-StablePay-Timestamp · string · 必填

Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。

X-StablePay-Nonce · string · 必填

防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。

Required string length: 16 - 64

X-StablePay-Signature · string · 必填

使用商户 API Secret 对 {timestamp}.{nonce}.{requestBody} 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 requestBody 为空字符串。

Idempotency-Key · string · 必填

商户范围内的请求幂等键，最长 128 个字符。

Required string length: 1 - 128

请求体

application/json

external_customer_id · string · 必填

商户系统客户 ID，必须为 10 位数字。

Pattern: ^[0-9]{10}$

allow_multiple_deposits · boolean · 必填

是否允许同一个二维码支付链接多次支付。

customer_name · string

客户姓名。客户首次创建时保存；已存在客户的资料不会被覆盖。

Maximum string length: 255

customer_email · string<email>

客户邮箱。客户首次创建时保存；已存在客户的资料不会被覆盖。

Maximum string length: 255

customer_phone · string

客户手机号。客户首次创建时保存；已存在客户的资料不会被覆盖。

Maximum string length: 50

expires_at · integer<int64>

过期时间，Unix 秒；必须晚于当前时间。省略表示永久有效，响应中返回 null。

description · string

二维码支付描述。

Maximum string length: 500

success_url · string<uri>

支付成功后的跳转地址，必须是绝对 HTTPS URL。

Maximum string length: 1024

cancel_url · string<uri>

用户取消支付后的跳转地址，必须是绝对 HTTPS URL。

Maximum string length: 1024

metadata · object

商户自定义元数据，最多 50 项；键长 1-64 个字符，值最长 500 个字符。

Show child attributes

响应

200

application/json

幂等重放，返回已创建的同一个二维码支付。

deposit_session_id · string · 必填

二维码支付 ID。

customer_id · string · 必填

StablePay 客户 ID。

status · enum<string> · 必填

二维码支付状态。

可用选项: active, closed, expired

allow_multiple_deposits · boolean · 必填

是否允许使用同一个二维码支付链接多次支付。

expires_at · integer<int64> | null · 必填

过期时间，Unix 秒；永久有效时固定返回 null。

url · string<uri> · 必填

托管收银台 URL。

metadata · object · 必填

商户自定义元数据。

Show child attributes

created · integer<int64> · 必填

创建时间，Unix 秒。