# 预授权、请款与撤销通知 > 接收预授权创建、请款和撤销回调报文，并通过同一支付意图关联授权生命周期。 ```yaml openapi: 3.1.0 info: title: 预授权、请款与撤销通知 version: 1.0.0 description: 接收预授权创建、请款和撤销回调报文，并通过同一支付意图关联授权生命周期。 webhooks: authorization.capture: 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 系统中应按字符串保存和比对，避免精度丢失。 - kind: consistency text: 同一授权生命周期中，`AUTH`、`CAPTURE` 与 `VOID` 是关联但不同的交易操作，各自 `transactionId` 不同。 x-onerway-signature-participation: included paymentId: type: string description: 支付意图 ID，用于关联原预授权及其后续请款或撤销操作。 x-onerway-constraints: - kind: rule text: 该值为大整数样式字符串；JavaScript 系统中应按字符串保存和比对，避免精度丢失。 - kind: consistency text: 同一预授权生命周期下的授权、请款与撤销操作可通过同一个 `paymentId` 关联。 x-onerway-signature-participation: included txnType: type: string description: 交易操作类型，表示本次通知对应预授权创建、请款还是撤销。 enum: - AUTH - CAPTURE - VOID x-enum-descriptions: AUTH: 预授权创建，对持卡人资金发起授权；是否已授权以 `status` 与 `paymentStatus` 为准。 CAPTURE: 预授权请款，对已授权金额发起请款。 VOID: 预授权撤销，释放已授权金额，不进行请款。 x-onerway-signature-participation: included merchantNo: type: string description: Onerway 分配的商户号，标识接收该通知的商户账户。 x-onerway-signature-participation: included merchantTxnId: type: string description: 商户交易号，用于对账和关联订单。 x-onerway-constraints: - kind: rule text: 请款通知可能回显原预授权订单的商户交易号；`VOID` 通知可返回撤销请求中的商户交易号。按 `transactionId` 对操作通知去重，并结合 `paymentId`、`transactionId` 与交易查询结果关联授权生命周期。 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: 原预授权订单金额；请款或撤销通知中表示关联原预授权金额。 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-constraints: - kind: consistency text: "`status` 表示本次操作结果；不要与支付意图级的 `paymentStatus` 混用。" x-onerway-signature-participation: included paymentStatus: type: string description: 支付意图级状态，表示预授权生命周期当前状态。 enum: - A - O - S - N x-enum-descriptions: A: 支付意图已授权，等待后续动作（如请款）。 O: 支付意图保持开放，可继续尝试。 S: 支付意图达到最终成功。 N: 支付意图已关闭。 x-onerway-constraints: - kind: rule text: "`AUTH` 成功后可返回 `A`（已授权，等待请款或撤销）；`AUTH` 失败时也可能返回 `O`（支付意图保持开放，可继续尝试）；`CAPTURE` 成功后可返回 `S`（支付意图成功）；`VOID` 成功后返回 `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 or 3DS transactions return ECI; it can be omitted when absent. zh: 卡交易或 3DS 交易返回 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 periodValue: type: - string - "null" description: 分期付款期数。 x-onerway-value: nullable: true empty: true when: en: Has a value for installment transactions; it may be an empty string or omitted when not applicable. zh: 分期交易返回期数时有值；不适用或未返回期数时可能为空字符串或不返回。 x-onerway-signature-participation: excluded 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 channelRequestId: type: string description: 支付渠道侧的请求标识，可用于渠道侧对账或排查。 x-onerway-signature-participation: included paymentMethodDetails: type: string description: 支付方式详情对象；卡交易的明细位于 `card` 子对象。 contentMediaType: application/json contentSchema: type: object properties: card: type: object 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 协议版本。 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 拒付责任承担方。 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 is `null` when absent. zh: 返回 3DS 验证结果时有值；未返回时为 `null`。 description: 验证检查结果，含 AVS 与 3DS 结果。 x-onerway-value: nullable: true when: en: Can contain AVS or 3DS verification results in `AUTH` notifications. `CAPTURE` or `VOID` notifications may return `null`. zh: "`AUTH` 通知中可能返回 AVS / 3DS 验证结果；`CAPTURE` 或 `VOID` 通知可能返回 `null`。" holderName: type: - string - "null" description: 持卡人姓名。 x-onerway-value: nullable: true when: en: Can be returned in `AUTH` notifications; `CAPTURE` or `VOID` notifications may return `null`. zh: "`AUTH` 通知可返回持卡人姓名；`CAPTURE` 或 `VOID` 通知可能为 `null`。" year: type: - string - "null" description: 卡有效期年份，4 位。 x-onerway-value: nullable: true when: en: Has a value when card expiry year is returned; `CAPTURE` or `VOID` notifications may return `null`. zh: 返回卡有效期时有值；`CAPTURE` 或 `VOID` 通知可能为 `null`。 month: type: - string - "null" description: 卡有效期月份，2 位（`01`-`12`）。 x-onerway-value: nullable: true when: en: Has a value when card expiry month is returned; `CAPTURE` or `VOID` notifications may return `null`. zh: 返回卡有效期时有值；`CAPTURE` 或 `VOID` 通知可能为 `null`。 cardType: type: - string - "null" description: 卡品牌 / 卡组织。 x-onerway-value: nullable: true when: en: Has a value when the card network returns the card brand; `VOID` notifications may return `null`. zh: 卡组织返回卡类型时有值；`VOID` 通知可能为 `null`。 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; `VOID` notifications may return `null`. zh: 卡组织返回卡产品类别时有值；`VOID` 通知可能为 `null`。 issuer: type: - string - "null" description: 发卡行名称。 x-onerway-value: nullable: true when: en: Has a value when the issuer can be identified; `CAPTURE` or `VOID` notifications may return `null`. zh: 可识别发卡行时有值；`CAPTURE` 或 `VOID` 通知可能为 `null`。 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 an authorization code is returned, including in successful `VOID` notifications. `AUTH` failure or `CAPTURE` notifications may return `null`. zh: 返回授权码时有值，成功的 `VOID` 通知也可返回授权码；`AUTH` 失败或 `CAPTURE` 通知可能为 `null`。 cardNumber: type: string description: 脱敏卡号，仅保留前 6 位和后 4 位，中间位掩码。 description: 卡支付方式详情。 x-onerway-format: json_string x-onerway-signature-participation: included examples: authorization_succeeded: summary: 预授权成功 value: notifyType: TXN transactionId: replace_with_authorization_transaction_id paymentId: replace_with_payment_id txnType: AUTH merchantNo: replace_with_merchant_no merchantTxnId: replace_with_merchant_transaction_id responseTime: 2026-05-01 03:08:19 txnTime: 2026-05-01 03:05:45 txnTimeZone: +08:00 orderAmount: "79.97" orderCurrency: USD status: S paymentStatus: A reason: '{"respCode":"20000","respMsg":"Success"}' sign: replace_with_sha256_signature paymentMethod: MASTERCARD channelRequestId: replace_with_channel_request_id paymentMethodDetails: '{"card":{"checks":null,"cardType":"MASTERCARD","cardNumber":"512345******0008"}}' capture_succeeded: summary: 预授权请款成功 value: notifyType: TXN transactionId: replace_with_capture_transaction_id paymentId: replace_with_payment_id txnType: CAPTURE merchantNo: replace_with_merchant_no merchantTxnId: replace_with_merchant_transaction_id responseTime: 2026-05-01 03:10:19 txnTime: 2026-05-01 03:10:12 txnTimeZone: +08:00 orderAmount: "79.97" orderCurrency: USD status: S paymentStatus: S reason: '{"respCode":"20000","respMsg":"Success"}' sign: replace_with_sha256_signature paymentMethod: MASTERCARD channelRequestId: replace_with_channel_request_id paymentMethodDetails: '{"card":{"checks":null,"cardNumber":"512345******0008"}}' void_succeeded: summary: 预授权撤销成功 value: notifyType: TXN transactionId: replace_with_void_transaction_id paymentId: replace_with_payment_id txnType: VOID merchantNo: replace_with_merchant_no merchantTxnId: replace_with_void_merchant_transaction_id responseTime: 2026-05-01 21:34:43 txnTime: 2026-05-01 15:33:51 txnTimeZone: +08:00 orderAmount: "0.01" orderCurrency: USD status: S paymentStatus: N cardBinCountry: HK reason: '{"respCode":"20000","respMsg":"Success"}' sign: replace_with_signature paymentMethod: VISA channelRequestId: replace_with_channel_request_id paymentMethodDetails: '{"card":{"checks":null,"holderName":null,"year":null,"month":null,"cardType":null,"productCategory":null,"issuer":null,"cardBinCountry":"HK","authorizationCode":"example_authorization_code","cardNumber":"example_masked_card_number"}}' 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 ```