# 支付结果通知

> 接收普通支付成功、失败、超时关闭或取消等支付结果回调报文。

```yaml
openapi: 3.1.0
info:
  title: 支付结果通知
  version: 1.0.0
  description: 接收普通支付成功、失败、超时关闭或取消等支付结果回调报文。
webhooks:
  payment.result:
    post:
      summary: 支付结果通知
      description: 接收普通支付成功、失败、超时关闭或取消等支付结果回调报文。
      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-constraints:
                    - kind: consistency
                      text: 不要与 `transactionId` 混用；`transactionId` 表示具体交易，`paymentId` 表示支付意图。
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Returned for transactions that formed a payment intent, including succeeded,
                        failed, or timed-out payments. Checkout cancellation
                        notifications do not return 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
                    - N
                  x-enum-descriptions:
                    S: 成功；交易已成功完成。
                    F: 失败；交易被拒绝或处理失败。
                    N: 已取消；交易未在有效期内完成支付（如收银台超时未付）而关闭。
                  x-onerway-constraints:
                    - kind: rule
                      text: "`S` 表示交易成功；`F` 表示交易失败或被拒绝；`N` 表示交易已取消。商户应以本字段判断当前 `transactionId`
                        的交易结果，并结合 `paymentStatus` 判断支付意图层状态。"
                  x-onerway-signature-participation: included
                paymentStatus:
                  type:
                    - string
                    - "null"
                  description: 支付意图级状态，用于读取同一 `paymentId` 下支付意图的生命周期状态。
                  enum:
                    - S
                    - O
                    - N
                    - null
                  x-enum-descriptions:
                    S: 支付意图达到最终成功。
                    O: 支付意图保持开放，可继续尝试。
                    N: 支付意图已关闭：超时未完成支付，包括下单后未支付关单与多次尝试均失败后关单。
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Has a value when the payment-intent state is returned. Succeeded payments
                        can return `S`; failed attempts where the payment intent
                        remains retryable can return `O`; timed-out payment
                        intents can return `N`. Checkout cancellation
                        notifications do not return it.
                      zh: 返回支付意图状态时有值；普通成功可返回 `S`，失败后支付意图仍可继续尝试时可返回 `O`，支付意图超时关闭时可返回 `N`；收银台订单取消通知不返回。
                  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. Local payments or flows with
                        no selected card may omit it.
                      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` 表示成功，`60005` 等表示失败原因，`50030` 表示订单取消原因，其余值按错误码或结果原因码处理。
                      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
                    - "null"
                  description: 本次交易使用的支付方式或卡品牌。
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Returned when a payment method has been selected. Checkout cancellation
                        notifications do not return it.
                      zh: 已选定支付方式时返回；收银台订单取消通知不返回。
                  x-onerway-signature-participation: excluded
                metaData:
                  type:
                    - string
                    - "null"
                  description: 商户自定义交易数据，用于商户侧关联订单、渠道或业务上下文；通知中按请求传入值返回。
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Returned when `metaData` was provided in the payment request. It can be
                        empty or omitted when no value is available.
                      zh: 支付请求传入 `metaData` 时返回；未传入或无可返回数据时可能为空或不返回。
                  x-onerway-signature-participation: included
                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 payment scenarios. Non-wallet payments do not return it.
                      zh: 钱包支付场景返回；非钱包支付不返回。
                  x-onerway-signature-participation: excluded
                channelRequestId:
                  type:
                    - string
                    - "null"
                  description: 支付渠道侧的请求标识，可用于渠道侧对账或排查。
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Returned after the transaction enters channel processing and a channel
                        request identifier is generated. Checkout cancellation
                        notifications do not return it.
                      zh: 交易进入支付渠道处理并生成渠道请求标识后返回；收银台订单取消通知不返回。
                  x-onerway-signature-participation: included
                products:
                  type:
                    - string
                    - "null"
                  description: 订单商品信息列表，通知中按 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: 商品数量。
                          x-onerway-constraints:
                            - kind: rule
                              text: 该值可能以 string 或 JSON number 返回；商户应在入库或对账前归一化。
                        currency:
                          type: string
                          description: 商品币种，[ISO
                            4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
                            三位字母货币代码。
                  x-onerway-value:
                    nullable: true
                    empty: true
                    when:
                      en: Has a value when checkout order product information is returned with the
                        notification. Ordinary card or local-payment
                        notifications may omit it.
                      zh: 收银台订单商品信息随通知返回时有值；普通卡支付 / 本地支付通知可能不返回。
                  x-onerway-format: json_string
                  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.
                                    zh: 返回 3DS 验证结果时有值。
                            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: Has a value when payment method details are returned. Card payment success,
                        failure, and payment-intent timeout notifications can
                        return it; local payments, simplified wallet
                        notifications, or order cancellations may omit it.
                      zh: 返回支付方式详情时有值；卡支付成功、支付失败或支付意图超时关闭均可能返回；本地支付、钱包简化通知或订单取消等场景可能不返回。
                  x-onerway-format: json_string
                  x-onerway-signature-participation: included
            examples:
              payment_result_success:
                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:52:23
                  txnTime: 2026-06-25 13:51:10
                  txnTimeZone: +08:00
                  orderAmount: "9.99"
                  orderCurrency: USD
                  status: S
                  paymentStatus: S
                  eci: "5"
                  cardBinCountry: US
                  reason: '{"respCode":"20000","respMsg":"Success"}'
                  sign: replace_with_sha256_signature
                  paymentMethod: MASTERCARD
                  metaData: '{"orderSource":"web","campaignId":"spring_sale"}'
                  channelRequestId: replace_with_channel_request_id
              payment_result_checkout_cancelled:
                summary: 收银台订单取消
                value:
                  notifyType: TXN
                  transactionId: replace_with_transaction_id
                  txnType: SALE
                  merchantNo: replace_with_merchant_no
                  merchantTxnId: replace_with_merchant_transaction_id
                  responseTime: 2026-06-25 13:52:23
                  txnTime: 2026-06-25 13:51:10
                  txnTimeZone: +08:00
                  orderAmount: "9.99"
                  orderCurrency: USD
                  status: N
                  reason: '{"respCode":"50030","respMsg":"Order canceled"}'
                  sign: replace_with_sha256_signature
      responses:
        "200":
          description: 成功接收并受理支付结果 webhook 后返回 HTTP 200，并在响应体中原样返回收到的 `transactionId`。
          content:
            text/plain:
              schema:
                type: string
              examples:
                return_transaction_id:
                  summary: 返回 transactionId
                  description: 使用 `text/plain` 应答，并在响应体中原样返回收到的通知中的 `transactionId`。请勿固定返回示例值。
                  value: replace_with_transaction_id
```