> ## 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. # 创建订阅 > 创建一个新的订阅。创建后订阅通常进入 `incomplete` 状态，需用户在返回的 `checkout_url` 完成首次授权付款后才进入 `active`（或 `trialing`）。请求头中的 `Idempotency-Key` 为必填幂等键。 ## OpenAPI ````yaml /zh/api/subscription-openapi.json post /api/v1/subscriptions/create openapi: 3.1.0 info: title: StablePay 订阅 API version: '2026-04-20' summary: StablePay 订阅相关接口：订阅管理、支付、支付方式、订阅退款与 Webhook 事件。 description: >- StablePay 订阅服务 OpenAPI 规范。 ## 基础信息 - Base URL: `https://api.stablepay.co` - 前缀: `/api/v1` - 协议: HTTPS - 数据格式: JSON (UTF-8) ## 认证 所有接口使用 `Authorization: Bearer {api_key}` 进行鉴权，并同时携带防重放签名头：`X-StablePay-Timestamp`、`X-StablePay-Nonce`、`X-StablePay-Signature`。无请求体的方法按空字符串参与签名。创建订阅时还必须额外携带 `Idempotency-Key` 请求头。 ## 金额精度 金额字段均使用币种的最小单位（如 USD 以分为单位，`1999` 代表 $19.99；USDT/USDC 使用 6 位精度）。 servers: - url: https://api.stablepay.co description: 生产环境 security: - bearerAuth: [] stablepayTimestamp: [] stablepayNonce: [] stablepaySignature: [] tags: - name: 订阅 description: 创建、查询、列出和取消订阅。 paths: /api/v1/subscriptions/create: post: tags: - 订阅 summary: 创建订阅 description: >- 创建一个新的订阅。创建后订阅通常进入 `incomplete` 状态，需用户在返回的 `checkout_url` 完成首次授权付款后才进入 `active`（或 `trialing`）。请求头中的 `Idempotency-Key` 为必填幂等键。 operationId: createSubscription parameters: - name: Idempotency-Key in: header required: true description: 商户生成的幂等键，最长 128 字符。相同键重试会返回首次创建的订阅对象。 schema: type: string maxLength: 128 example: sub_create_20260430_0001 - $ref: '#/components/parameters/XStablePayTimestamp' - $ref: '#/components/parameters/XStablePayNonce' - $ref: '#/components/parameters/XStablePaySignature' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionRequest' example: items: - price_data: price_id: price_monthly_001 currency: USD product: Pro Plan unit_amount: 1999 recurring: interval: month quantity: 1 customer: cust_001 customer_email: alice@example.com customer_name: Alice currency: USD description: Pro 月付计划 success_url: https://merchant.example/success cancel_url: https://merchant.example/cancel metadata: merchant_order_no: sub_order_1001 responses: '200': description: 订阅创建成功；重复使用相同 `Idempotency-Key` 时返回首次创建的订阅对象。 content: application/json: schema: $ref: '#/components/schemas/Subscription' '400': description: 请求参数错误。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: 认证失败。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: 服务器错误。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: XStablePayTimestamp: name: X-StablePay-Timestamp in: header required: true description: Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。 schema: type: string example: '1735689600' 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: CreateSubscriptionRequest: type: object required: - items - customer properties: items: type: array minItems: 1 maxItems: 1 description: 订阅项列表，当前仅支持 1 个元素。 items: $ref: '#/components/schemas/CreateSubscriptionItem' customer: type: string description: 外部客户 ID（商户侧客户标识）。 customer_email: type: string format: email description: 客户邮箱。 customer_phone: type: string description: 客户手机号。 customer_name: type: string maxLength: 255 description: 客户姓名。 currency: type: string enum: - USD - usd description: 订阅币种。当前仅支持 `USD`，可省略并由 price_data.currency 决定。 description: type: string maxLength: 500 description: 订阅描述。 success_url: type: string maxLength: 512 description: 用户完成首次付款后的跳转 URL，最长 512 字符。 cancel_url: type: string maxLength: 512 description: 用户取消首次付款后的跳转 URL，最长 512 字符。 trial_end: type: integer format: int64 description: 试用期结束时间，Unix 秒。与 `billing_cycle_anchor` 互斥。 billing_cycle_anchor: type: integer format: int64 description: 账期锚点时间，Unix 秒。与 `trial_end` 互斥；非试用场景必须为未来时间或当前/过去时间代表立即扣首期。 cancel_at: type: integer format: int64 description: 计划取消时间，Unix 秒。必须为未来时间，且与 `iterations` 互斥。 iterations: type: integer minimum: 1 description: 运行 N 个周期后自动取消。必须大于 0，且与 `cancel_at` 互斥。 metadata: type: object additionalProperties: true description: 商户自定义元数据。 Subscription: type: object description: 订阅对象。 properties: id: type: string description: 订阅 ID。 object: type: string example: subscription customer: type: string description: 外部客户 ID。 store_id: type: string description: 店铺 ID。 currency: type: string description: 币种。 description: type: string description: 订阅描述。 status: $ref: '#/components/schemas/SubscriptionStatus' items: type: array items: $ref: '#/components/schemas/SubscriptionItem' description: 订阅项列表。 payment_method_id: type: string description: 默认支付方式 ID。 billing_cycle_anchor: type: integer format: int64 description: 账期锚点，Unix 秒。 current_period_start: type: integer format: int64 description: 当前周期开始，Unix 秒。 current_period_end: type: integer format: int64 description: 当前周期结束，Unix 秒。 canceled_at: type: integer format: int64 description: 取消完成时间，Unix 秒。 cancel_at: type: integer format: int64 description: 计划取消时间，Unix 秒。 latest_invoice: type: string description: 最近一张发票 ID。 latest_invoice_object: allOf: - $ref: '#/components/schemas/Invoice' description: '`expand=latest_invoice` 时返回完整发票对象。' customer_object: allOf: - $ref: '#/components/schemas/Customer' description: '`expand=customer` 时返回完整客户对象。' payment_method_object: allOf: - $ref: '#/components/schemas/PaymentMethod' description: '`expand=payment_method` 时返回完整支付方式对象。' checkout_url: type: string description: 首次付款收银台 URL，仅创建时返回。 metadata: type: object additionalProperties: true description: 商户自定义元数据。 created: type: integer format: int64 description: 创建时间，Unix 秒。 ErrorResponse: type: object description: 错误响应。 properties: error: type: object properties: type: type: string description: 错误类型。 code: type: string description: 错误代码。 message: type: string description: 错误信息。 param: type: string description: 相关参数。 doc_url: type: string description: 错误文档链接。 decline_code: type: string description: 拒绝代码。 request_log_url: type: string description: 请求日志链接。 charge: type: string description: 相关支付 ID。 request_id: type: string description: 请求 ID。 timestamp: type: integer format: int64 description: 错误发生时间，Unix 秒。 CreateSubscriptionItem: type: object required: - price_data - quantity properties: price_data: $ref: '#/components/schemas/CreateSubscriptionPriceData' quantity: type: integer minimum: 1 description: 数量。当前实现未设置默认值，必须传入且大于等于 1。 metadata: type: object additionalProperties: true description: 订阅项元数据。 SubscriptionStatus: type: string enum: - incomplete - trialing - active - past_due - canceled - incomplete_expired description: 订阅状态。 SubscriptionItem: type: object properties: id: type: string description: 订阅项 ID。 price_data: $ref: '#/components/schemas/PriceData' quantity: type: integer minimum: 1 description: 数量。 metadata: type: object additionalProperties: true description: 订阅项元数据。 Invoice: type: object required: - id - object - subscription_id - customer - amount_due - amount_paid - amount_remaining - currency - status - payment_status - billing_reason - period_start - period_end - created properties: id: type: string description: 发票 ID。 object: type: string example: invoice subscription_id: type: string description: 关联订阅 ID。 customer: type: string description: 客户 ID。 amount_due: type: integer format: int64 description: 应付金额，使用最小单位。 amount_paid: type: integer format: int64 description: 已支付金额，使用最小单位。 amount_remaining: type: integer format: int64 description: 未支付金额，使用最小单位。 currency: type: string description: 币种。 status: $ref: '#/components/schemas/InvoiceStatus' payment_status: type: string enum: - pending - processing - completed - failed - canceled - expired description: 发票支付状态。 billing_reason: type: string description: 开票原因，例如 `subscription_create`、`subscription_cycle`。 frequency: type: string description: 计费频率展示文本，例如 `Monthly`。 recurring_interval: type: string enum: - day - week - month - year description: 重复计费周期。 recurring_interval_count: type: integer format: int32 description: 重复计费周期数量。 period_start: type: integer format: int64 description: 计费周期开始，Unix 秒。 period_end: type: integer format: int64 description: 计费周期结束，Unix 秒。 payment_id: type: string description: 关联支付会话 ID。优先返回 payment_session_id，其次返回 trade_order_id。 paid_at: type: integer format: int64 description: 支付完成时间，Unix 秒。 due_date: type: integer format: int64 description: 到期时间，Unix 秒。 created: type: integer format: int64 description: 创建时间，Unix 秒。 Customer: type: object properties: id: type: string description: 客户 ID。 object: type: string example: customer merchant_id: type: string description: 商户 ID。 external_customer_id: type: string description: 外部客户 ID。 email: type: string format: email description: 客户邮箱。 name: type: string description: 客户姓名。 phone: type: string description: 客户手机号。 default_payment_method: type: string description: 默认支付方式 ID。 description: type: string description: 客户描述。 created: type: integer format: int64 description: 创建时间，Unix 秒。 PaymentMethod: type: object properties: id: type: string description: 支付方式 ID。 object: type: string example: payment_method customer: type: string description: 客户 ID。 merchant_id: type: string description: 商户 ID。 type: type: string description: 支付方式类型。 currency: type: string description: 币种。 chain_type: type: integer format: int32 description: 链类型。 status: type: string enum: - active - inactive - revoked - unknown description: 支付方式状态。 mandate_id: type: string description: 授权 ID。 metadata: type: object additionalProperties: true description: 元数据。 created: type: integer format: int64 description: 创建时间，Unix 秒。 CreateSubscriptionPriceData: type: object required: - price_id - currency - product - unit_amount - recurring properties: price_id: type: string description: 价格对象 ID，必填，用于业务幂等/识别。 currency: type: string enum: - USD - usd description: 价格币种，当前仅支持 `USD`。 product: type: string description: 产品 ID 或产品名称，不能为空。 unit_amount: type: integer format: int64 minimum: 1 description: 单价，使用最小单位，必须大于 0。 recurring: $ref: '#/components/schemas/CreateSubscriptionRecurringConfig' PriceData: type: object properties: id: type: string description: 价格 ID。当前 HTTP 响应通常不返回该字段。 currency: type: string description: 币种。 product: type: string description: 产品 ID 或产品名称。 unit_amount: type: integer format: int64 description: 单价，使用最小单位。 recurring: $ref: '#/components/schemas/RecurringConfig' InvoiceStatus: type: string enum: - open - paid - void description: 发票状态。 CreateSubscriptionRecurringConfig: type: object required: - interval properties: interval: type: string enum: - day - week - month - year description: 计费周期。 RecurringConfig: type: object properties: interval: type: string enum: - day - week - month - year description: 计费周期。 interval_count: type: integer description: 计费间隔数。当前服务端固定为 1。 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 个字符，建议每次请求使用新的 UUID。 stablepaySignature: type: apiKey in: header name: X-StablePay-Signature description: >- 使用商户 API Secret 对 `{timestamp}.{nonce}.{requestBody}` 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 `requestBody` 为空字符串。 ````