> ## Documentation Index > Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt > Use this file to discover all available pages before exploring further. # 创建客户充值支付 > 根据商户系统的 10 位客户 ID 创建充值支付及托管收银台链接。客户不存在时会在当前商户范围内自动创建。 `external_customer_id` 必须为 10 位数字，`allow_multiple_deposits` 必填。创建请求还必须携带 `Idempotency-Key`。 ## OpenAPI ````yaml /zh/api/customer-deposits.openapi.json post /api/v1/customer-deposits openapi: 3.1.0 info: title: StablePay 客户充值支付 API version: '2026-10-13' summary: 客户充值支付创建和查询 API。 description: >- StablePay 客户充值支付 API 的 OpenAPI 规范。 说明： - 基础 URL：https://api.stablepay.co - 认证方式：Bearer API Key + `X-StablePay-Timestamp` + `X-StablePay-Nonce` + `X-StablePay-Signature` - 签名字符串：`{timestamp}.{nonce}.{requestBody}` - 签名算法：HMAC-SHA256，小写 hex - GET 请求的 `requestBody` 为空字符串 - StablePay 根据 `external_customer_id` 在当前商户范围内自动识别或创建客户 - 商户身份由鉴权网关注入，请求参数不得传入 `merchant_id` servers: - url: https://api.stablepay.co description: 生产环境 security: - bearerAuth: [] stablepayTimestamp: [] stablepayNonce: [] stablepaySignature: [] tags: - name: 客户充值支付 description: 创建和查询客户充值支付及托管收银台链接。 paths: /api/v1/customer-deposits: post: tags: - 客户充值支付 summary: 创建客户充值支付 description: >- 根据商户系统的 10 位客户 ID 创建充值支付及托管收银台链接。客户不存在时会在当前商户范围内自动创建。 `external_customer_id` 必须为 10 位数字，`allow_multiple_deposits` 必填。创建请求还必须携带 `Idempotency-Key`。 operationId: createCustomerDeposit parameters: - $ref: '#/components/parameters/XStablePayTimestamp' - $ref: '#/components/parameters/XStablePayNonce' - $ref: '#/components/parameters/XStablePaySignature' - name: Idempotency-Key in: header required: true description: 商户范围内的请求幂等键，最长 128 个字符。 schema: type: string minLength: 1 maxLength: 128 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCustomerDepositRequest' example: external_customer_id: '1234567890' customer_name: Example Customer customer_email: customer@example.com allow_multiple_deposits: true description: Account top-up success_url: https://merchant.example/deposit/success cancel_url: https://merchant.example/deposit/cancel metadata: reference: CRM-10001 responses: '200': description: 幂等重放，返回已创建的同一个充值支付。 content: application/json: schema: $ref: '#/components/schemas/CustomerDepositSession' '201': description: 首次创建成功。 content: application/json: schema: $ref: '#/components/schemas/CustomerDepositSession' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalError' components: parameters: XStablePayTimestamp: name: X-StablePay-Timestamp in: header required: true description: Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。 schema: type: string example: '1791878400' XStablePayNonce: name: X-StablePay-Nonce in: header required: true description: 防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。 schema: type: string minLength: 16 maxLength: 64 example: 550e8400-e29b-41d4-a716-446655440000 XStablePaySignature: name: X-StablePay-Signature in: header required: true description: >- 使用商户 API Secret 对 `{timestamp}.{nonce}.{requestBody}` 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 `requestBody` 为空字符串。 schema: type: string example: a1b2c3d4e5f6... schemas: CreateCustomerDepositRequest: type: object required: - external_customer_id - allow_multiple_deposits properties: external_customer_id: type: string pattern: ^[0-9]{10}$ description: 商户系统客户 ID，必须为 10 位数字。 customer_name: type: string maxLength: 255 description: 客户姓名。客户首次创建时保存；已存在客户的资料不会被覆盖。 customer_email: type: string format: email maxLength: 255 description: 客户邮箱。客户首次创建时保存；已存在客户的资料不会被覆盖。 customer_phone: type: string maxLength: 50 description: 客户手机号。客户首次创建时保存；已存在客户的资料不会被覆盖。 expires_at: type: integer format: int64 description: 过期时间，Unix 秒；必须晚于当前时间。省略表示永久有效，响应中返回 null。 allow_multiple_deposits: type: boolean description: 是否允许同一个充值链接多次充值。 description: type: string maxLength: 500 description: 充值支付描述。 success_url: type: string format: uri maxLength: 1024 description: 支付成功后的跳转地址，必须是绝对 HTTPS URL。 cancel_url: type: string format: uri maxLength: 1024 description: 用户取消支付后的跳转地址，必须是绝对 HTTPS URL。 metadata: type: object maxProperties: 50 propertyNames: minLength: 1 maxLength: 64 additionalProperties: type: string maxLength: 500 description: 商户自定义元数据，最多 50 项；键长 1-64 个字符，值最长 500 个字符。 additionalProperties: false CustomerDepositSession: type: object required: - deposit_session_id - customer_id - status - allow_multiple_deposits - expires_at - url - metadata - created properties: deposit_session_id: type: string description: 充值支付 ID。 customer_id: type: string description: StablePay 客户 ID。 status: type: string enum: - active - closed - expired description: 充值支付状态。 allow_multiple_deposits: type: boolean description: 是否允许使用同一个链接多次充值。 expires_at: type: - integer - 'null' format: int64 description: 过期时间，Unix 秒；永久有效时固定返回 null。 url: type: string format: uri description: 托管收银台 URL。 metadata: type: object additionalProperties: type: string description: 商户自定义元数据。 created: type: integer format: int64 description: 创建时间，Unix 秒。 ErrorResponse: type: object required: - code - message - errorCode - data description: 错误响应。 properties: code: type: integer description: HTTP 状态码。 message: type: string description: 错误信息。 errorCode: type: string description: 稳定的业务错误代码。 data: type: 'null' description: 错误响应中固定为 null。 responses: BadRequest: description: 请求参数无效。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: 鉴权失败。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Conflict: description: 幂等键冲突。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalError: description: 服务内部错误。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: Bearer API Key，例如 `Bearer sk_live_xxx`。 stablepayTimestamp: type: apiKey in: header name: X-StablePay-Timestamp description: Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。 stablepayNonce: type: apiKey in: header name: X-StablePay-Nonce description: 防重放随机字符串，长度 16-64 个字符。 stablepaySignature: type: apiKey in: header name: X-StablePay-Signature description: 使用商户 API Secret 计算的 HMAC-SHA256 小写 hex 签名。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.