# 订阅扣款通知

> 接收包含订阅合约、token 与扣款场景上下文的首次或后续订阅扣款回调报文。

```yaml
openapi: 3.1.0
info:
  title: 订阅扣款通知
  version: 1.0.0
  description: 接收包含订阅合约、token 与扣款场景上下文的首次或后续订阅扣款回调报文。
webhooks:
  subscription.payment:
    post:
      summary: 订阅扣款通知
      description: 接收包含订阅合约、token 与扣款场景上下文的首次或后续订阅扣款回调报文。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                notifyType:
                  type: string
                  description: 通知类型，标识本次 Webhook 的业务大类。
                  x-onerway-constraints:
                    - kind: values
                      text: 订阅扣款通知固定返回 `TXN`。
                  x-onerway-signature-participation: included
                transactionId:
                  type: string
                  description: Onerway 为本次订阅扣款生成的交易号，用于跟踪、查询和幂等处理。
                  x-onerway-constraints:
                    - kind: rule
                      text: 该值为大整数样式字符串；JavaScript 系统中应按字符串保存和比对，避免精度丢失。
                  x-onerway-signature-participation: included
                paymentId:
                  type:
                    - string
                    - "null"
                  description: 支付意图 ID，用于按支付意图维度关联本次订阅扣款链路。
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Can be returned for both initial and renewal payments; some initial
                        subscription payment notifications may omit it.
                      zh: 首次扣款和后续扣款均可返回；部分首次扣款通知可能不返回。
                  x-onerway-signature-participation: included
                txnType:
                  type: string
                  description: 交易操作类型，表示本次通知对应的交易动作。
                  enum:
                    - SALE
                  x-enum-descriptions:
                    SALE: 支付。
                  x-onerway-constraints:
                    - kind: values
                      text: 订阅扣款通知固定返回 `SALE`。
                  x-onerway-signature-participation: included
                merchantNo:
                  type: string
                  description: Onerway 分配的商户号，标识接收该通知的商户账户。
                  x-onerway-signature-participation: included
                merchantTxnId:
                  type: string
                  description: 商户交易号，可用于商户侧对账、去重和关联订阅扣款订单。
                  x-onerway-signature-participation: included
                responseTime:
                  type: string
                  description: Onerway 生成本次通知结果的时间，格式为 `yyyy-MM-dd HH:mm:ss`。
                  x-onerway-signature-participation: included
                txnTime:
                  type: string
                  description: 本次扣款交易发生或交易状态形成的时间，格式为 `yyyy-MM-dd HH:mm:ss`。
                  x-onerway-signature-participation: included
                txnTimeZone:
                  type: string
                  description: "`txnTime` 使用的时区偏移，格式为 `±HH:mm`。"
                  x-onerway-signature-participation: included
                orderAmount:
                  type: string
                  description: 本次订阅扣款金额，以 `orderCurrency` 表示。
                  x-onerway-constraints:
                    - kind: rule
                      text: 金额以 decimal string 返回，商户系统应避免用二进制浮点数直接计算金额。
                  x-onerway-signature-participation: included
                orderCurrency:
                  type: string
                  description: 本次订阅扣款币种，[ISO
                    4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
                    三位字母货币代码。
                  x-onerway-signature-participation: included
                status:
                  type: string
                  description: 本次订阅扣款交易处理状态。
                  enum:
                    - S
                    - F
                    - P
                    - R
                    - N
                    - I
                    - U
                  x-enum-descriptions:
                    S: 成功；交易已成功完成。
                    F: 失败；交易被拒绝或处理失败。
                    P: 处理中；交易正在处理。
                    R: 需跳转；客户需被跳转以完成支付。
                    N: 已取消；交易未在有效期内完成支付（如收银台超时未付）而关闭。
                    I: 审核中；交易待审批或人工复核。
                    U: 未支付；等待支付。
                  x-onerway-signature-participation: included
                paymentStatus:
                  type:
                    - string
                    - "null"
                  description: 支付意图级状态，用于读取本次扣款支付意图的生命周期状态。
                  enum:
                    - I
                    - U
                    - P
                    - R
                    - A
                    - O
                    - S
                    - N
                    - null
                  x-enum-descriptions:
                    I: 支付意图已初始化。
                    U: 支付意图待支付。
                    P: 支付意图处理中。
                    R: 支付意图需要跳转。
                    A: 支付意图已授权。
                    O: 支付意图保持开放。
                    S: 支付意图达到最终成功。
                    N: 支付意图已关闭：超时未完成支付，包括下单后未支付关单与多次尝试均失败后关单。
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Can be returned for both initial and renewal payments; some initial
                        subscription payment notifications may omit it.
                      zh: 首次扣款和后续扣款均可返回；部分首次扣款通知可能不返回。
                  x-onerway-signature-participation: included
                contractId:
                  type: string
                  description: 订阅合约号，标识本次扣款所属的订阅合约；商户需保存并用于后续订阅查询、取消或更新。
                  x-onerway-constraints:
                    - kind: rule
                      text: 该值为大整数样式字符串；JavaScript 系统中应按字符串保存和比对，避免精度丢失。
                  x-onerway-signature-participation: included
                tokenId:
                  type: string
                  description: 订阅 token。请与 `contractId` 一起保存，后续订阅扣款、查询和取消都需要这两个值。
                  x-onerway-constraints:
                    - kind: rule
                      text: 该 token 仅用于订阅相关操作；它不是保存支付方式 token，不能用于 `subProductType=TOKEN` 支付。
                    - kind: consistency
                      text: 传入 `subscription.bindCard=true` 的卡订阅：保存支付方式 token 通过本通知的 `cardTokenId`
                        返回，与本字段无关。本地支付方式订阅：[保存支付方式结果通知](/zh/payments/api-reference/webhooks/payment-method-result)的
                        `tokenId` 与该值相同，同样是订阅 token。钱包支付订阅只有本通知。
                  x-onerway-signature-participation: included
                cardTokenId:
                  type:
                    - string
                    - "null"
                  description: 本次订阅所用卡片的保存支付方式 token。
                  x-onerway-constraints:
                    - kind: consistency
                      text: 与[保存支付方式结果通知](/zh/payments/api-reference/webhooks/payment-method-result)的
                        `tokenId` 相同，可据此匹配两条通知；它与本通知的 `tokenId` 是不同的 token。
                    - kind: rule
                      text: 卡是否保存成功以保存支付方式结果通知为准：仅在该通知返回 `status=S` 后，才可将此 token
                        用于[创建直连交易](/zh/payments/api-reference/endpoints/direct-create-transaction)的
                        `subProductType=TOKEN` 支付。Onerway
                        在本次支付成功后才执行保存卡，支付失败不会发送保存支付方式结果通知。两条通知到达商户服务器的先后顺序不保证，请分别做幂等处理。
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Returned only when the initial card subscription was created with
                        `subscription.bindCard=true` and this payment succeeded
                        (`status=S`). Not returned for card subscriptions
                        without `bindCard`, renewal payments, wallet
                        subscriptions, or local payment method subscriptions.
                      zh: 仅当首次卡订阅传入了 `subscription.bindCard=true` 且本次支付成功（`status=S`）时返回；未传 `bindCard`
                        的卡订阅、续费扣款、钱包支付订阅和本地支付方式订阅均不返回。
                  x-onerway-signature-participation: included
                eci:
                  type:
                    - string
                    - "null"
                  description: 电子商务指示符（ECI），表示交易相关的 3DS 认证状态。
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Has a value when card, 3DS, or wallet transactions return ECI.
                      zh: 卡交易或 3DS / wallet 交易返回 ECI 时有值。
                  x-onerway-signature-participation: included
                cardBinCountry:
                  type:
                    - string
                    - "null"
                  description: 卡 BIN 所属国家 / 地区，[ISO 3166-1
                    alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
                    两位字母代码。
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Has a value when this is a card transaction and the card BIN country or
                        region can be identified.
                      zh: 卡交易且可识别卡 BIN 所属国家 / 地区时有值。
                  x-onerway-signature-participation: included
                reason:
                  type: string
                  description: 交易结果原因对象，通知中按 JSON string 承载。
                  contentMediaType: application/json
                  contentSchema:
                    type: object
                    properties:
                      respCode:
                        type: string
                        description: 结果码；`20000` 表示成功，其余为错误码。
                      respMsg:
                        type: string
                        description: 结果码对应的可读说明。
                  x-onerway-format: json_string
                  x-onerway-signature-participation: included
                sign:
                  type: string
                  description: 兼容保留的签名字符串：仅使用第一个启用的密钥计算，密钥轮换期间可能与商户配置的密钥不一致；请改用 `X-Rh-Signature`
                    header 验签。
                  x-onerway-constraints:
                    - kind: rule
                      text: 验签时不要把 `sign` 自身作为待签名字段。
                  x-onerway-signature-participation: signature-field
                paymentMethod:
                  type: string
                  description: 本次订阅扣款使用的支付方式或卡品牌。
                  x-onerway-signature-participation: excluded
                walletTypeName:
                  type:
                    - string
                    - "null"
                  description: 钱包类型名称。
                  enum:
                    - GooglePay
                    - ApplePay
                    - EXPR
                    - JIOU
                    - XJK
                    - null
                  x-enum-descriptions:
                    GooglePay: Google Pay 钱包。
                    ApplePay: Apple Pay 钱包。
                    EXPR: 钱包内资金来源：银行卡。
                    JIOU: 钱包内资金来源：白条。
                    XJK: 钱包内资金来源：小金库。
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Returned for wallet subscriptions. Not returned for card or local payment
                        method subscriptions.
                      zh: 钱包支付订阅返回；卡订阅和本地支付方式订阅不返回。
                  x-onerway-signature-participation: excluded
                subscriptionManageUrl:
                  type:
                    - string
                    - "null"
                  description: 订阅管理地址，买家可通过该地址查看和管理该订阅。
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Has a value when a subscription management URL is returned; some
                        subscription payment notifications may omit it.
                      zh: 返回订阅管理地址时有值；部分订阅扣款通知可能不返回。
                  x-onerway-signature-participation: included
                subscriptionStatus:
                  type: string
                  description: 订阅合约当前生命周期状态。
                  enum:
                    - trialing
                    - paymentdue
                    - active
                    - pastdue
                    - paused
                    - canceled
                    - ended
                  x-enum-descriptions:
                    trialing: 试用期内；付费订阅开始前的试用期。
                    paymentdue: 待付款；用户待付款或付款处理中，订阅合同尚未生效。
                    active: 订阅生效中；订阅状态正常，所有款项已支付。
                    pastdue: 付款逾期；当前周期已结束但续扣失败，订阅合同仍然有效。
                    paused: 临时暂停；某期扣款尝试全部失败后订阅暂停，合约仍处于启用状态。
                    canceled: 已取消；用户或商户在计划结束前终止订阅。
                    ended: 已结束；达到自然结束日期或完成所有计费周期。
                  x-onerway-signature-participation: included
                dataStatus:
                  type: string
                  description: 订阅合约启用状态。
                  enum:
                    - "0"
                    - "1"
                    - "2"
                    - "3"
                  x-enum-descriptions:
                    "0": 待启用。
                    "1": 启用。
                    "2": 停用。
                    "3": 已取消。
                  x-onerway-signature-participation: included
                products:
                  type: string
                  description: 订阅请求中 `txnOrderMsg.products` 提交的商品列表，通知中按 JSON string 返回。
                  contentMediaType: application/json
                  contentSchema:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: 商品名称。
                        price:
                          type: string
                          description: 商品单价，使用 decimal string。
                          x-onerway-constraints:
                            - kind: rule
                              text: 金额以 decimal string 返回，商户系统应避免用二进制浮点数直接计算金额。
                        num:
                          type: string
                          description: 商品数量。
                        currency:
                          type: string
                          description: 商品币种，[ISO
                            4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
                            三位字母货币代码。
                        type:
                          type:
                            - string
                            - "null"
                          description: 请求中 `txnOrderMsg.products[].type` 提交的商品项类型。
                          x-onerway-value:
                            nullable: true
                            empty: true
                            when:
                              en: Empty string or omitted when the request did not submit it.
                              zh: 请求未提交时为空字符串或不返回。
                        retailerId:
                          type:
                            - string
                            - "null"
                          description: 销售该商品的零售商标识。
                          x-onerway-value:
                            nullable: true
                            empty: true
                            when:
                              en: Has a value when the subscription was created with retailer information.
                                Subscriptions without retailers do not return
                                it.
                              zh: 订阅创建时传入了零售商信息时有值；未传 retailers 的订阅不返回。
                          x-onerway-lifecycle:
                            status: new
                            since: 2026-08-10
                            description:
                              en: New field linking each product to its retailer.
                              zh: 将商品关联到零售商的新增字段。
                  x-onerway-format: json_string
                  x-onerway-signature-participation: included
                metaData:
                  type:
                    - string
                    - "null"
                  description: 请求中提交的商户自定义数据，按原始 JSON 字符串原样返回。
                  x-onerway-constraints:
                    - kind: consistency
                      text: 同时提交了外层 `metaData` 与 `subscription.metaData` 时，本字段返回
                        `subscription.metaData`。
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Returned when `metaData` was submitted in the request; empty or omitted
                        otherwise.
                      zh: 请求提交了 `metaData` 时返回，否则为空或不返回。
                  x-onerway-signature-participation: included
                channelRequestId:
                  type: string
                  description: 支付渠道侧的请求标识，可用于渠道侧对账或排查。
                  x-onerway-signature-participation: included
                scenarios:
                  type:
                    - string
                    - "null"
                  description: 触发本次通知的订阅场景，区分首次扣款、后续扣款、换卡、订阅变更、订阅取消与到期结束等生命周期事件。
                  enum:
                    - SUBSCRIPTION_INITIAL
                    - SUBSCRIPTION_RENEWAL
                    - SUBSCRIPTION_CARD_REPLACEMENT
                    - SUBSCRIPTION_CHANGED
                    - SUBSCRIPTION_CANCELED
                    - SUBSCRIPTION_ENDED
                    - null
                  x-enum-descriptions:
                    SUBSCRIPTION_INITIAL: 首次订阅扣款，通常与订阅合约创建同时发生。
                    SUBSCRIPTION_RENEWAL: 后续周期扣款，使用已保存的 `contractId` 与 `tokenId` 完成本期扣款。
                    SUBSCRIPTION_CARD_REPLACEMENT: 订阅支付方式更新，例如为现有订阅替换已过期或失效的卡。
                    SUBSCRIPTION_CHANGED: 订阅计划变更，例如升级、降级或计划条款调整。
                    SUBSCRIPTION_CANCELED: 订阅取消，由客户或商户发起，停止后续扣款。
                    SUBSCRIPTION_ENDED: 订阅到期结束，合同达到预定的结束时间后自然终止。
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Returned for card and wallet subscriptions, including renewals. For local
                        payment method subscriptions, the scenario is returned
                        in the Saved payment method result webhook instead, and
                        this notification for the first charge omits it.
                      zh: 卡订阅和钱包支付订阅（含续费）返回；本地支付方式订阅的订阅场景由保存支付方式结果通知返回，首次扣款的本通知不返回。
                  x-onerway-signature-participation: included
                paymentMethodDetails:
                  type:
                    - string
                    - "null"
                  description: 支付方式详情对象；卡交易的明细位于 `card` 子对象。
                  contentMediaType: application/json
                  contentSchema:
                    type: object
                    properties:
                      card:
                        type:
                          - object
                          - "null"
                        properties:
                          checks:
                            type:
                              - object
                              - "null"
                            properties:
                              addressCheck:
                                type:
                                  - string
                                  - "null"
                                description: AVS 街道地址校验结果。
                                enum:
                                  - pass
                                  - fail
                                  - unavailable
                                  - unchecked
                                  - notProvided
                                  - unsupported
                                  - null
                                x-enum-descriptions:
                                  pass: 提交验证的信息与发卡行记录一致。
                                  fail: 提交验证的信息与发卡行记录不一致。
                                  unavailable: 发卡行不支持此类验证。
                                  unchecked: 未执行验证。
                                  notProvided: 未提供本次验证所需的信息。
                                  unsupported: 此交易不支持 AVS。
                                x-onerway-value:
                                  nullable: true
                                  when:
                                    en: Has a value when AVS street-address verification was performed.
                                    zh: 执行 AVS 街道地址校验时有值。
                              postalCodeCheck:
                                type:
                                  - string
                                  - "null"
                                description: AVS 邮政编码校验结果。
                                enum:
                                  - pass
                                  - fail
                                  - unavailable
                                  - unchecked
                                  - notProvided
                                  - unsupported
                                  - null
                                x-enum-descriptions:
                                  pass: 提交验证的信息与发卡行记录一致。
                                  fail: 提交验证的信息与发卡行记录不一致。
                                  unavailable: 发卡行不支持此类验证。
                                  unchecked: 未执行验证。
                                  notProvided: 未提供本次验证所需的信息。
                                  unsupported: 此交易不支持 AVS。
                                x-onerway-value:
                                  nullable: true
                                  when:
                                    en: Has a value when AVS postal-code verification was performed.
                                    zh: 执行 AVS 邮编校验时有值。
                              cardholderNameCheck:
                                type:
                                  - string
                                  - "null"
                                description: American Express AVS 持卡人姓名验证结果，表示姓名是否与发卡行记录一致。
                                enum:
                                  - pass
                                  - fail
                                  - unavailable
                                  - unchecked
                                  - notProvided
                                  - unsupported
                                  - null
                                x-enum-descriptions:
                                  pass: 提交验证的信息与发卡行记录一致。
                                  fail: 提交验证的信息与发卡行记录不一致。
                                  unavailable: 发卡行不支持此类验证。
                                  unchecked: 未执行验证。
                                  notProvided: 未提供本次验证所需的信息。
                                  unsupported: 此交易不支持 AVS。
                                x-onerway-value:
                                  nullable: true
                                  when:
                                    en: Returns the result when American Express cardholder name verification is
                                      performed, or `null` if it is not
                                      performed.
                                    zh: 执行 American Express 持卡人姓名验证时返回验证结果；未执行时返回 `null`。
                              avsResultRawCode:
                                type:
                                  - string
                                  - "null"
                                description: 卡组织返回的原始 AVS 结果码。
                                enum:
                                  - N
                                  - S
                                  - U
                                  - R
                                  - W
                                  - Z
                                  - X
                                  - Y
                                  - M
                                  - F
                                  - D
                                  - A
                                  - B
                                  - P
                                  - G
                                  - I
                                  - C
                                  - FD
                                  - NP
                                  - null
                                x-enum-descriptions:
                                  N: 邮政编码和街道地址都不匹配。
                                  S: 不支持 AVS。
                                  U: 验证服务不可用。
                                  R: 系统无法执行。
                                  W: 9 位邮编匹配，地址不匹配。
                                  Z: 5 位邮编匹配，地址不匹配。
                                  X: 9 位邮编和地址都匹配。
                                  Y: 5 位邮编和地址都匹配。
                                  M: 地址和邮编匹配（仅国际）。
                                  F: 地址和邮编匹配（仅英国）。
                                  D: 地址和邮编匹配（仅国际）。
                                  A: 地址匹配，邮编不匹配。
                                  B: 地址匹配，邮编未验证。
                                  P: 邮编匹配，地址未验证。
                                  G: 非 AVS 参与者（美国境外）。
                                  I: 国际交易地址未验证。
                                  C: 地址和邮编未验证（非美国 Visa 卡）。
                                  FD: AVS 验证不可用（Onerway 系统码）。
                                  NP: 未提供地址和邮编（Onerway 系统码）。
                                x-onerway-value:
                                  nullable: true
                                  when:
                                    en: Has a value when the card network or Onerway returns a raw AVS result code.
                                    zh: 卡组织或 Onerway 返回原始 AVS 结果码时有值。
                              threeDSecureResult:
                                type:
                                  - object
                                  - "null"
                                properties:
                                  version:
                                    type: string
                                    description: 3D Secure 协议版本或 `UNKNOWN`。
                                  authenticationFlow:
                                    type:
                                      - string
                                      - "null"
                                    description: 3DS 认证流程类型。
                                    x-onerway-value:
                                      nullable: true
                                      when:
                                        en: Has a value when the 3DS authentication flow can be identified.
                                        zh: 可识别 3DS 认证流程时有值。
                                  chargebackLiability:
                                    type: string
                                    description: 3DS 拒付责任承担方或 `UNKNOWN`。
                                  transStatus:
                                    type:
                                      - string
                                      - "null"
                                    description: 3DS 认证结果。
                                    x-onerway-value:
                                      nullable: true
                                      when:
                                        en: Has a value when ACS returns an authentication status.
                                        zh: ACS 返回认证状态时有值。
                                  transStatusReason:
                                    type:
                                      - string
                                      - "null"
                                    description: 3DS 认证状态的详细原因说明。
                                    x-onerway-value:
                                      nullable: true
                                      when:
                                        en: Has a value when the authentication status includes a detailed reason.
                                        zh: 需要补充说明 3DS 认证状态时有值。
                                  veresEnrolled:
                                    type:
                                      - string
                                      - "null"
                                    description: 3DS enrollment 结果。
                                    x-onerway-value:
                                      nullable: true
                                      when:
                                        en: Has a value when the 3DS enrollment result is returned.
                                        zh: 3DS enrollment 结果返回时有值。
                                  eci:
                                    type:
                                      - string
                                      - "null"
                                    description: 电子商务指示符（ECI）。
                                    x-onerway-value:
                                      nullable: true
                                      when:
                                        en: Has a value when the 3DS result returns ECI.
                                        zh: 3DS 结果返回 ECI 时有值。
                                  cvvResult:
                                    type:
                                      - string
                                      - "null"
                                    description: CVV 安全码校验结果。
                                    enum:
                                      - M
                                      - N
                                      - P
                                      - S
                                      - U
                                      - I
                                      - null
                                    x-enum-descriptions:
                                      M: CVV 匹配成功。
                                      N: CVV 不匹配。
                                      P: CVV 处理错误。
                                      S: CVV 缺失。
                                      U: 系统不可用。
                                      I: CVV 无效。
                                    x-onerway-value:
                                      nullable: true
                                      when:
                                        en: Has a value when the CVV check result is returned.
                                        zh: CVV 校验结果返回时有值。
                                  avsFullResult:
                                    type:
                                      - string
                                      - "null"
                                    description: AVS 地址验证综合结果。
                                    enum:
                                      - Y
                                      - N
                                      - A
                                      - Z
                                      - U
                                      - null
                                    x-enum-descriptions:
                                      Y: 邮政编码与街道地址都匹配。
                                      N: 邮政编码与街道地址都不匹配。
                                      A: 街道地址匹配，邮政编码不匹配。
                                      Z: 邮政编码匹配，街道地址不匹配。
                                      U: 系统不可用。
                                    x-onerway-value:
                                      nullable: true
                                      when:
                                        en: Has a value when the AVS full-result value is returned.
                                        zh: AVS 综合校验结果返回时有值。
                                  cavvResult:
                                    type:
                                      - string
                                      - "null"
                                    description: 3DS 认证返回的 CAVV 加密值。
                                    x-onerway-value:
                                      nullable: true
                                      when:
                                        en: Has a value when 3DS authentication returns CAVV.
                                        zh: 3DS 认证返回 CAVV 时有值。
                                description: 3D Secure 验证结果。
                                x-onerway-value:
                                  nullable: true
                                  when:
                                    en: Has a value when 3DS verification results are returned; it can be `null`
                                      when absent.
                                    zh: 返回 3DS 验证结果时有值；未返回时可为 `null`。
                            description: 验证检查结果，含 AVS 与 3DS 结果。
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Has a value when the payment channel returns AVS, 3DS, or CVV verification
                                  results.
                                zh: 支付渠道返回 AVS / 3DS / CVV 验证结果时有值；未执行或未返回验证结果时可为 `null`。
                          holderName:
                            type:
                              - string
                              - "null"
                            description: 持卡人姓名。
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Has a value when cardholder name is returned; wallet transactions can return
                                  `null`.
                                zh: 支付方式详情返回持卡人姓名时有值；钱包交易可能为 `null`。
                          year:
                            type:
                              - string
                              - "null"
                            description: 卡有效期年份，4 位。
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Has a value when card expiry year is returned.
                                zh: 返回卡有效期时有值。
                          month:
                            type:
                              - string
                              - "null"
                            description: 卡有效期月份，2 位（`01`-`12`）。
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Has a value when card expiry month is returned.
                                zh: 返回卡有效期时有值。
                          cardType:
                            type:
                              - string
                              - "null"
                            description: 卡品牌 / 卡组织。
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Has a value when the card network returns the card brand.
                                zh: 卡组织返回卡类型时有值。
                          productCategory:
                            type:
                              - string
                              - "null"
                            description: 卡产品类别。
                            enum:
                              - D
                              - P
                              - C
                              - H
                              - R
                              - N
                              - null
                            x-enum-descriptions:
                              D: 借记卡
                              P: 预付卡
                              C: 信用卡
                              H: 签账卡
                              R: 延迟借记卡
                              N: 未知
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Has a value when the card network returns the product category.
                                zh: 卡组织返回卡产品类别时有值。
                          issuer:
                            type:
                              - string
                              - "null"
                            description: 发卡行名称。
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Has a value when the issuer can be identified.
                                zh: 可识别发卡行时有值。
                          cardBinCountry:
                            type:
                              - string
                              - "null"
                            description: 卡 BIN 所属国家 / 地区。
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Has a value when the card BIN country or region can be identified.
                                zh: 可识别卡 BIN 所属国家 / 地区时有值。
                          authorizationCode:
                            type:
                              - string
                              - "null"
                            description: 发卡行或收单侧授权码，可用于对账与争议处理。
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Has a value when a card transaction is authorized successfully and an
                                  authorization code is returned.
                                zh: 卡交易授权成功并返回授权码时有值。
                          cardNumber:
                            type:
                              - string
                              - "null"
                            description: 脱敏卡号，仅保留前 6 位和后 4 位，中间位掩码。
                            x-onerway-value:
                              nullable: true
                              when:
                                en: Has a value when masked card number is returned.
                                zh: 返回脱敏卡号时有值。
                        description: 卡支付方式详情。
                        x-onerway-value:
                          nullable: true
                          when:
                            en: Has a value when card or wallet-card details are returned.
                            zh: 卡支付或钱包卡交易返回卡详情时有值。
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Returned when card details are available. Not returned for local payment
                        method subscriptions; some wallet subscriptions omit it.
                      zh: 有卡详情时返回；本地支付方式订阅不返回，部分钱包支付订阅不返回。
                  x-onerway-format: json_string
                  x-onerway-signature-participation: included
            examples:
              subscription_initial_card_saved_card:
                summary: 首次卡订阅并保存卡
                value:
                  notifyType: TXN
                  transactionId: replace_with_card_sale_transaction_id
                  paymentId: replace_with_card_sale_payment_id
                  txnType: SALE
                  merchantNo: replace_with_merchant_no
                  merchantTxnId: replace_with_merchant_subscription_reference
                  responseTime: 2026-01-15 10:10:02
                  txnTime: 2026-01-15 10:10:00
                  txnTimeZone: +08:00
                  orderAmount: "7.00"
                  orderCurrency: USD
                  status: S
                  paymentStatus: S
                  contractId: replace_with_subscription_contract_id
                  tokenId: replace_with_subscription_token
                  cardTokenId: replace_with_saved_card_token
                  eci: "05"
                  cardBinCountry: US
                  reason: '{"respCode":"20000","respMsg":"Success"}'
                  sign: replace_with_sha256_signature
                  paymentMethod: VISA
                  subscriptionManageUrl: https://developers.onerway.com/example-subscription-manage
                  subscriptionStatus: active
                  dataStatus: "1"
                  products: '[{"currency":"USD","name":"Example weekly
                    plan","num":"1","price":"7.00","type":""}]'
                  metaData: '{"plan":"weekly"}'
                  channelRequestId: replace_with_card_sale_channel_request_id
                  scenarios: SUBSCRIPTION_INITIAL
                  paymentMethodDetails: '{"card":{"checks":{"addressCheck":null,"postalCodeCheck":null,"cardholderNameCheck":null,"avsResultRawCode":null,"threeDSecureResult":{"version":"UNKNOWN","authenticationFlow":"CHALLENGE","chargebackLiability":"UNKNOWN","transStatus":null,"transStatusReason":null,"veresEnrolled":null,"eci":"05","cvvResult":null,"avsFullResult":null,"cavvResult":"replace_with_cavv"}},"holderName":"Example
                    Cardholder","year":"2028","month":"05","cardType":null,"productCategory":null,"issuer":"Example
                    Issuer","cardBinCountry":"US","authorizationCode":null,"cardNumber":"400000******0002"}}'
              subscription_initial_card:
                summary: 不保存卡的首次卡订阅
                value:
                  notifyType: TXN
                  transactionId: replace_with_initial_sale_transaction_id
                  paymentId: replace_with_initial_sale_payment_id
                  txnType: SALE
                  merchantNo: replace_with_merchant_no
                  merchantTxnId: replace_with_merchant_subscription_reference
                  responseTime: 2026-01-15 10:20:02
                  txnTime: 2026-01-15 10:20:00
                  txnTimeZone: +08:00
                  orderAmount: "7.00"
                  orderCurrency: USD
                  status: S
                  paymentStatus: S
                  contractId: replace_with_subscription_contract_id
                  tokenId: replace_with_subscription_token
                  eci: "05"
                  cardBinCountry: US
                  reason: '{"respCode":"20000","respMsg":"Success"}'
                  sign: replace_with_sha256_signature
                  paymentMethod: VISA
                  subscriptionManageUrl: https://developers.onerway.com/example-subscription-manage
                  subscriptionStatus: active
                  dataStatus: "1"
                  products: '[{"currency":"USD","name":"Example weekly
                    plan","num":"1","price":"7.00","type":""}]'
                  metaData: '{"plan":"weekly"}'
                  channelRequestId: replace_with_initial_sale_channel_request_id
                  scenarios: SUBSCRIPTION_INITIAL
                  paymentMethodDetails: '{"card":{"checks":null,"holderName":"Example
                    Cardholder","year":"2028","month":"05","cardType":null,"productCategory":null,"issuer":"Example
                    Issuer","cardBinCountry":"US","authorizationCode":null,"cardNumber":"400000******0002"}}'
              subscription_renewal_payment:
                summary: 订阅后续扣款
                value:
                  notifyType: TXN
                  transactionId: replace_with_transaction_id
                  paymentId: replace_with_payment_id
                  txnType: SALE
                  merchantNo: replace_with_merchant_no
                  merchantTxnId: replace_with_merchant_transaction_id
                  responseTime: 2026-06-25 13:56:28
                  txnTime: 2026-06-25 13:56:26
                  txnTimeZone: +08:00
                  orderAmount: "29.99"
                  orderCurrency: USD
                  status: S
                  paymentStatus: S
                  contractId: replace_with_subscription_contract_id
                  tokenId: replace_with_subscription_token_id
                  reason: '{"respCode":"20000","respMsg":"Success"}'
                  sign: replace_with_sha256_signature
                  paymentMethod: VISA
                  subscriptionStatus: active
                  dataStatus: "1"
                  products: '[{"name":"Unlimited","price":"29.99","num":"1","currency":"USD"}]'
                  channelRequestId: replace_with_channel_request_id
                  scenarios: SUBSCRIPTION_RENEWAL
              subscription_renewal_google_pay:
                summary: Google Pay 订阅后续扣款
                value:
                  notifyType: TXN
                  transactionId: replace_with_transaction_id
                  paymentId: replace_with_payment_id
                  txnType: SALE
                  merchantNo: replace_with_merchant_no
                  merchantTxnId: replace_with_merchant_transaction_id
                  responseTime: 2026-06-25 14:12:09
                  txnTime: 2026-06-25 14:12:07
                  txnTimeZone: +08:00
                  orderAmount: "17.99"
                  orderCurrency: USD
                  status: S
                  paymentStatus: S
                  contractId: replace_with_subscription_contract_id
                  tokenId: replace_with_subscription_token_id
                  eci: "7"
                  cardBinCountry: US
                  reason: '{"respCode":"20000","respMsg":"Success"}'
                  sign: replace_with_sha256_signature
                  paymentMethod: VISA
                  walletTypeName: GooglePay
                  subscriptionStatus: active
                  dataStatus: "1"
                  products: '[{"name":"Example unlimited
                    plan","price":"17.99","num":"1","currency":"USD"}]'
                  channelRequestId: replace_with_channel_request_id
                  scenarios: SUBSCRIPTION_RENEWAL
                  paymentMethodDetails: '{"card":{"checks":{"addressCheck":null,"postalCodeCheck":null,"cardholderNameCheck":null,"avsResultRawCode":null,"threeDSecureResult":{"version":"UNKNOWN","authenticationFlow":null,"chargebackLiability":"MERCHANT","transStatus":null,"transStatusReason":null,"veresEnrolled":null,"eci":"07","cvvResult":null,"avsFullResult":null,"cavvResult":null}},"holderName":null,"year":"2027","month":"07","cardType":null,"productCategory":null,"issuer":"Example
                    Issuer","cardBinCountry":"US","authorizationCode":"replace_with_authorization_code","cardNumber":"400000******0002"}}'
              subscription_renewal_apple_pay:
                summary: Apple Pay 订阅后续扣款
                value:
                  notifyType: TXN
                  transactionId: replace_with_transaction_id
                  paymentId: replace_with_payment_id
                  txnType: SALE
                  merchantNo: replace_with_merchant_no
                  merchantTxnId: replace_with_merchant_transaction_id
                  responseTime: 2026-06-25 14:31:44
                  txnTime: 2026-06-25 14:31:41
                  txnTimeZone: +08:00
                  orderAmount: "18.99"
                  orderCurrency: USD
                  status: S
                  paymentStatus: S
                  contractId: replace_with_subscription_contract_id
                  tokenId: replace_with_subscription_token_id
                  eci: "7"
                  cardBinCountry: US
                  reason: '{"respCode":"20000","respMsg":"Success"}'
                  sign: replace_with_sha256_signature
                  paymentMethod: MASTERCARD
                  walletTypeName: ApplePay
                  subscriptionStatus: active
                  dataStatus: "1"
                  products: '[{"name":"Example unlimited
                    plan","price":"18.99","num":"1","currency":"USD"}]'
                  channelRequestId: replace_with_channel_request_id
                  scenarios: SUBSCRIPTION_RENEWAL
                  paymentMethodDetails: '{"card":{"checks":{"addressCheck":null,"postalCodeCheck":null,"cardholderNameCheck":null,"avsResultRawCode":null,"threeDSecureResult":{"version":"UNKNOWN","authenticationFlow":null,"chargebackLiability":"MERCHANT","transStatus":null,"transStatusReason":null,"veresEnrolled":null,"eci":"07","cvvResult":null,"avsFullResult":null,"cavvResult":null}},"holderName":null,"year":"2027","month":"10","cardType":null,"productCategory":null,"issuer":"Example
                    Issuer","cardBinCountry":"US","authorizationCode":"replace_with_authorization_code","cardNumber":"512345******0008"}}'
              subscription_initial_lpms:
                summary: DANA 订阅首次扣款
                value:
                  notifyType: TXN
                  transactionId: replace_with_lpms_sale_transaction_id
                  paymentId: replace_with_lpms_payment_id
                  txnType: SALE
                  merchantNo: replace_with_merchant_no
                  merchantTxnId: replace_with_merchant_subscription_reference
                  responseTime: 2026-01-15 10:30:04
                  txnTime: 2026-01-15 10:30:03
                  txnTimeZone: +08:00
                  orderAmount: "39000.00"
                  orderCurrency: IDR
                  status: S
                  paymentStatus: S
                  contractId: replace_with_lpms_subscription_contract_id
                  tokenId: replace_with_lpms_subscription_token
                  reason: '{"respCode":"20000","respMsg":"Success"}'
                  sign: replace_with_sha256_signature
                  paymentMethod: DANA
                  subscriptionStatus: active
                  dataStatus: "1"
                  products: '[{"currency":"IDR","name":"Example monthly
                    plan","num":"1","price":"39000.00"}]'
                  channelRequestId: replace_with_lpms_sale_channel_request_id
              subscription_initial_google_pay:
                summary: Google Pay 首次订阅
                value:
                  notifyType: TXN
                  transactionId: replace_with_wallet_sale_transaction_id
                  paymentId: replace_with_wallet_sale_payment_id
                  txnType: SALE
                  merchantNo: replace_with_merchant_no
                  merchantTxnId: replace_with_merchant_subscription_reference
                  responseTime: 2026-01-15 10:40:02
                  txnTime: 2026-01-15 10:40:00
                  txnTimeZone: +08:00
                  orderAmount: "20.00"
                  orderCurrency: USD
                  status: S
                  paymentStatus: S
                  contractId: replace_with_wallet_subscription_contract_id
                  tokenId: replace_with_wallet_subscription_token
                  eci: "05"
                  cardBinCountry: US
                  reason: '{"respCode":"20000","respMsg":"Success"}'
                  sign: replace_with_sha256_signature
                  paymentMethod: VISA
                  walletTypeName: GooglePay
                  subscriptionStatus: active
                  dataStatus: "1"
                  products: '[{"currency":"USD","name":"Example subscription
                    product","num":"1","price":"20.00","type":""}]'
                  channelRequestId: replace_with_wallet_sale_channel_request_id
                  scenarios: SUBSCRIPTION_INITIAL
                  paymentMethodDetails: '{"card":{"checks":null,"holderName":"Example
                    Cardholder","year":"2028","month":"05","cardType":null,"productCategory":null,"issuer":"Example
                    Issuer","cardBinCountry":"US","authorizationCode":null,"cardNumber":"400000******0002"}}'
              subscription_initial_apple_pay:
                summary: Apple Pay 首次订阅
                value:
                  notifyType: TXN
                  transactionId: replace_with_apple_pay_sale_transaction_id
                  txnType: SALE
                  merchantNo: replace_with_merchant_no
                  merchantTxnId: replace_with_merchant_subscription_reference
                  responseTime: 2026-01-15 10:50:21
                  txnTime: 2026-01-15 10:50:00
                  txnTimeZone: +08:00
                  orderAmount: "29.99"
                  orderCurrency: USD
                  status: S
                  contractId: replace_with_apple_pay_subscription_contract_id
                  tokenId: replace_with_apple_pay_subscription_token
                  eci: "5"
                  cardBinCountry: US
                  reason: '{"respCode":"20000","respMsg":"Success"}'
                  sign: replace_with_sha256_signature
                  paymentMethod: VISA
                  walletTypeName: ApplePay
                  subscriptionManageUrl: https://developers.onerway.com/example-subscription-manage
                  subscriptionStatus: active
                  dataStatus: "1"
                  products: '[{"name":"Example subscription
                    product","price":"29.99","num":"1","currency":"USD"}]'
                  channelRequestId: replace_with_apple_pay_sale_channel_request_id
                  scenarios: SUBSCRIPTION_INITIAL
      responses:
        "200":
          description: 成功接收并受理订阅扣款 webhook 后返回 HTTP 200，并在响应体中原样返回收到的 `transactionId`。
          content:
            text/plain:
              schema:
                type: string
              examples:
                return_transaction_id:
                  summary: 返回 transactionId
                  description: 使用 `text/plain` 应答，并在响应体中返回收到的 webhook payload 内的 `transactionId`。
                  value: replace_with_transaction_id
```