Skip to main content
POST

授权

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 个字符。

响应

幂等重放,返回已创建的同一个充值支付。

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
必填

商户自定义元数据。

created
integer<int64>
必填

创建时间,Unix 秒。

最后修改于 2026年10月13日