POST

订阅扣款通知

回调地址

该回调通知用于接收订阅扣款结果，并通过 contractId、tokenId 和 scenarios 关联对应订阅扣款场景。

验签范围

请求签名指南

除以下字段外，全部回调报文字段均参与验签：

notifyTypestring

通知类型，标识本次 Webhook 的业务大类。

约束

取值: 订阅扣款通知固定返回 TXN。

transactionIdstring

Onerway 为本次订阅扣款生成的交易号，用于跟踪、查询和幂等处理。

约束

规则: 该值为大整数样式字符串；JavaScript 系统中应按字符串保存和比对，避免精度丢失。

paymentIdstring

支付意图 ID，用于按支付意图维度关联本次订阅扣款链路。

txnTypestring

交易操作类型，表示本次通知对应的交易动作。

可选值

SALE: 支付。

约束

取值: 订阅扣款通知固定返回 SALE。

merchantNostring

Onerway 分配的商户号，标识接收该通知的商户账户。

merchantTxnIdstring

商户交易号，可用于商户侧对账、去重和关联订阅扣款订单。

responseTimestring

Onerway 生成本次通知结果的时间，格式为 yyyy-MM-dd HH:mm:ss。

txnTimestring

本次扣款交易发生或交易状态形成的时间，格式为 yyyy-MM-dd HH:mm:ss。

txnTimeZonestring

txnTime 使用的时区偏移，格式为 ±HH:mm。

orderAmountstring

本次订阅扣款金额，以 orderCurrency 表示。

约束

规则: 金额以 decimal string 返回，商户系统应避免用二进制浮点数直接计算金额。

orderCurrencystring

本次订阅扣款币种，ISO 4217 三位字母货币代码。

statusstring

本次订阅扣款交易处理状态。

可选值

S: 成功；交易已成功完成。
F: 失败；交易被拒绝或处理失败。
P: 处理中；交易正在处理。

paymentStatusstring

支付意图级状态，用于读取本次扣款支付意图的生命周期状态。

可选值

I: 支付意图已初始化。
U: 支付意图待支付。
P: 支付意图处理中。

contractIdstring

订阅合约号，标识本次扣款所属的订阅合约；商户需保存并用于后续订阅查询、取消或更新。

约束

规则: 该值为大整数样式字符串；JavaScript 系统中应按字符串保存和比对，避免精度丢失。

tokenIdstring

订阅 token。请与 contractId 一起保存，后续订阅扣款、查询和取消都需要这两个值。

约束

规则: 该 token 仅用于订阅相关操作；它不是保存支付方式 token，不能用于 subProductType=TOKEN 支付。
一致性: 传入 subscription.bindCard=true 的卡订阅：保存支付方式 token 通过本通知的 cardTokenId 返回，与本字段无关。本地支付方式订阅：保存支付方式结果通知的 tokenId 与该值相同，同样是订阅 token。钱包支付订阅只有本通知。

cardTokenIdstring

本次订阅所用卡片的保存支付方式 token。

约束

一致性: 与保存支付方式结果通知的 tokenId 相同，可据此匹配两条通知；它与本通知的 tokenId 是不同的 token。
规则: 卡是否保存成功以保存支付方式结果通知为准：仅在该通知返回 status=S 后，才可将此 token 用于创建直连交易的 subProductType=TOKEN 支付。Onerway 在本次支付成功后才执行保存卡，支付失败不会发送保存支付方式结果通知。两条通知到达商户服务器的先后顺序不保证，请分别做幂等处理。

ecistring

电子商务指示符（ECI），表示交易相关的 3DS 认证状态。

cardBinCountrystring

卡 BIN 所属国家 / 地区，ISO 3166-1 alpha-2 两位字母代码。

reasonobject{2}{ respCode, respMsg }

交易结果原因对象，通知中按 JSON string 承载。

signstring签名字段 · 不参与验签

兼容保留的签名字符串：仅使用第一个启用的密钥计算，密钥轮换期间可能与商户配置的密钥不一致；请改用 X-Rh-Signature header 验签。

约束

规则: 验签时不要把 sign 自身作为待签名字段。

paymentMethodstring不参与验签

本次订阅扣款使用的支付方式或卡品牌。

walletTypeNamestring不参与验签

钱包类型名称。

可选值

GooglePay: Google Pay 钱包。
ApplePay: Apple Pay 钱包。
EXPR: 钱包内资金来源：银行卡。

subscriptionManageUrlstring

订阅管理地址，买家可通过该地址查看和管理该订阅。

subscriptionStatusstring

订阅合约当前生命周期状态。

可选值

trialing: 试用期内；付费订阅开始前的试用期。
paymentdue: 待付款；用户待付款或付款处理中，订阅合同尚未生效。
active: 订阅生效中；订阅状态正常，所有款项已支付。

dataStatusstring

订阅合约启用状态。

可选值

0: 待启用。
1: 启用。
2: 停用。

productsarray<object>[6]{ name, price, ... }

订阅请求中 txnOrderMsg.products 提交的商品列表，通知中按 JSON string 返回。

metaDatastring

请求中提交的商户自定义数据，按原始 JSON 字符串原样返回。

约束

一致性: 同时提交了外层 metaData 与 subscription.metaData 时，本字段返回 subscription.metaData。

channelRequestIdstring

支付渠道侧的请求标识，可用于渠道侧对账或排查。

scenariosstring

触发本次通知的订阅场景，区分首次扣款、后续扣款、换卡、订阅变更、订阅取消与到期结束等生命周期事件。

可选值

SUBSCRIPTION_INITIAL: 首次订阅扣款，通常与订阅合约创建同时发生。
SUBSCRIPTION_RENEWAL: 后续周期扣款，使用已保存的 contractId 与 tokenId 完成本期扣款。
SUBSCRIPTION_CARD_REPLACEMENT: 订阅支付方式更新，例如为现有订阅替换已过期或失效的卡。

paymentMethodDetailsobject{26}{ card }

支付方式详情对象；卡交易的明细位于 card 子对象。

应答说明

成功接收并受理订阅扣款 webhook 后返回 HTTP 200，并在响应体中原样返回收到的 transactionId。

POST

{
  "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\"}}"
}

使用 text/plain 应答，并在响应体中返回收到的 webhook payload 内的 transactionId。

replace_with_transaction_id

POST

订阅扣款通知

回调地址

该回调通知用于接收订阅扣款结果，并通过 contractId、tokenId 和 scenarios 关联对应订阅扣款场景。

验签范围

请求签名指南

除以下字段外，全部回调报文字段均参与验签：

notifyTypestring

通知类型，标识本次 Webhook 的业务大类。

约束

取值: 订阅扣款通知固定返回 TXN。

transactionIdstring

Onerway 为本次订阅扣款生成的交易号，用于跟踪、查询和幂等处理。

约束

规则: 该值为大整数样式字符串；JavaScript 系统中应按字符串保存和比对，避免精度丢失。

paymentIdstring

支付意图 ID，用于按支付意图维度关联本次订阅扣款链路。

txnTypestring

交易操作类型，表示本次通知对应的交易动作。

可选值

SALE: 支付。

约束

取值: 订阅扣款通知固定返回 SALE。

merchantNostring

Onerway 分配的商户号，标识接收该通知的商户账户。

merchantTxnIdstring

商户交易号，可用于商户侧对账、去重和关联订阅扣款订单。

responseTimestring

Onerway 生成本次通知结果的时间，格式为 yyyy-MM-dd HH:mm:ss。

txnTimestring

本次扣款交易发生或交易状态形成的时间，格式为 yyyy-MM-dd HH:mm:ss。

txnTimeZonestring

txnTime 使用的时区偏移，格式为 ±HH:mm。

orderAmountstring

本次订阅扣款金额，以 orderCurrency 表示。

约束

规则: 金额以 decimal string 返回，商户系统应避免用二进制浮点数直接计算金额。

orderCurrencystring

本次订阅扣款币种，ISO 4217 三位字母货币代码。

statusstring

本次订阅扣款交易处理状态。

可选值

S: 成功；交易已成功完成。
F: 失败；交易被拒绝或处理失败。
P: 处理中；交易正在处理。

paymentStatusstring

支付意图级状态，用于读取本次扣款支付意图的生命周期状态。

可选值

I: 支付意图已初始化。
U: 支付意图待支付。
P: 支付意图处理中。

contractIdstring

订阅合约号，标识本次扣款所属的订阅合约；商户需保存并用于后续订阅查询、取消或更新。

约束

规则: 该值为大整数样式字符串；JavaScript 系统中应按字符串保存和比对，避免精度丢失。

tokenIdstring

订阅 token。请与 contractId 一起保存，后续订阅扣款、查询和取消都需要这两个值。

约束

规则: 该 token 仅用于订阅相关操作；它不是保存支付方式 token，不能用于 subProductType=TOKEN 支付。
一致性: 传入 subscription.bindCard=true 的卡订阅：保存支付方式 token 通过本通知的 cardTokenId 返回，与本字段无关。本地支付方式订阅：保存支付方式结果通知的 tokenId 与该值相同，同样是订阅 token。钱包支付订阅只有本通知。

cardTokenIdstring

本次订阅所用卡片的保存支付方式 token。

约束

一致性: 与保存支付方式结果通知的 tokenId 相同，可据此匹配两条通知；它与本通知的 tokenId 是不同的 token。
规则: 卡是否保存成功以保存支付方式结果通知为准：仅在该通知返回 status=S 后，才可将此 token 用于创建直连交易的 subProductType=TOKEN 支付。Onerway 在本次支付成功后才执行保存卡，支付失败不会发送保存支付方式结果通知。两条通知到达商户服务器的先后顺序不保证，请分别做幂等处理。

ecistring

电子商务指示符（ECI），表示交易相关的 3DS 认证状态。

cardBinCountrystring

卡 BIN 所属国家 / 地区，ISO 3166-1 alpha-2 两位字母代码。

reasonobject{2}{ respCode, respMsg }

交易结果原因对象，通知中按 JSON string 承载。

signstring签名字段 · 不参与验签

兼容保留的签名字符串：仅使用第一个启用的密钥计算，密钥轮换期间可能与商户配置的密钥不一致；请改用 X-Rh-Signature header 验签。

约束

规则: 验签时不要把 sign 自身作为待签名字段。

paymentMethodstring不参与验签

本次订阅扣款使用的支付方式或卡品牌。

walletTypeNamestring不参与验签

钱包类型名称。

可选值

GooglePay: Google Pay 钱包。
ApplePay: Apple Pay 钱包。
EXPR: 钱包内资金来源：银行卡。

subscriptionManageUrlstring

订阅管理地址，买家可通过该地址查看和管理该订阅。

subscriptionStatusstring

订阅合约当前生命周期状态。

可选值

trialing: 试用期内；付费订阅开始前的试用期。
paymentdue: 待付款；用户待付款或付款处理中，订阅合同尚未生效。
active: 订阅生效中；订阅状态正常，所有款项已支付。

dataStatusstring

订阅合约启用状态。

可选值

0: 待启用。
1: 启用。
2: 停用。

productsarray<object>[6]{ name, price, ... }

订阅请求中 txnOrderMsg.products 提交的商品列表，通知中按 JSON string 返回。

metaDatastring

请求中提交的商户自定义数据，按原始 JSON 字符串原样返回。

约束

一致性: 同时提交了外层 metaData 与 subscription.metaData 时，本字段返回 subscription.metaData。

channelRequestIdstring

支付渠道侧的请求标识，可用于渠道侧对账或排查。

scenariosstring

触发本次通知的订阅场景，区分首次扣款、后续扣款、换卡、订阅变更、订阅取消与到期结束等生命周期事件。

可选值

SUBSCRIPTION_INITIAL: 首次订阅扣款，通常与订阅合约创建同时发生。
SUBSCRIPTION_RENEWAL: 后续周期扣款，使用已保存的 contractId 与 tokenId 完成本期扣款。
SUBSCRIPTION_CARD_REPLACEMENT: 订阅支付方式更新，例如为现有订阅替换已过期或失效的卡。

paymentMethodDetailsobject{26}{ card }

支付方式详情对象；卡交易的明细位于 card 子对象。

{
  "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\"}}"
}

应答说明

成功接收并受理订阅扣款 webhook 后返回 HTTP 200，并在响应体中原样返回收到的 transactionId。

使用 text/plain 应答，并在响应体中返回收到的 webhook payload 内的 transactionId。

replace_with_transaction_id

支付结果通知

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

预授权、请款与撤销通知

接收预授权创建、请款和撤销回调报文，并通过同一支付意图关联授权生命周期。

验签范围

回调报文字段

应答说明

验签范围

回调报文字段

回调示例

应答说明

应答正文示例