通知

注意事项

通知地址可在商户注册时配置，或通过交易请求中的 notifyUrl 参数指定
notifyUrl 参数优先级更高。如两者均未配置，则不发送通知
支付结果以 webhook 通知为准，请勿仅依赖同步响应中的 status 字段

安全加固建议

以下措施可显著提升通知接收端的安全性，建议至少实施其中一项：

IP 白名单限制

来自 Onerway 的请求将从以下 IP 地址发出。建议在服务器防火墙或应用层对通知接口配置 IP 白名单，拒绝其他来源的请求，防止伪造通知攻击。

环境	IP 地址
生产环境	`20.68.8.122`
生产环境	`18.207.78.37`
生产环境	`52.70.96.9`
生产环境	`54.160.200.158`
生产环境	`44.219.164.167`
Sandbox	`27.109.125.90`

主动查询确认订单状态

异步通知存在网络抖动、延迟或丢失的可能。建议在收到通知后，额外调用交易订单查询 API 主动查询，以查询结果作为最终订单状态的依据，避免仅依赖通知数据导致状态不一致。

以下场景尤为重要

通知处于重试窗口期（T+30min / T+60min）
通知到达时，系统正在维护或 webhook 接口暂时不可用
需要对重复通知进行去重校验

Transaction 与 Payment 双层状态语义（使用支付意图模型的商户适用）

transactionId：单次交易尝试的流水号（attempt 维度），业务类型为 Long，JSON 以 String 传输。
status：当前 transactionId 对应的交易状态（transaction 维度）。
paymentId：支付意图主键，一个 paymentId 可关联多笔 transactionId。
paymentStatus：支付意图状态（payment 维度），独立于单笔交易 status。

兼容性说明：未使用支付意图模型的商户可忽略 paymentId/paymentStatus，继续仅处理 status。使用支付意图模型的商户需同时处理 status 与 paymentStatus。

关单场景通知规则（paymentStatus = N，使用支付意图模型的商户适用）

paymentStatus = N 表示支付意图超时关闭，包含两种场景：

用户下单后未支付，超时关单。
用户多次尝试均失败，最终超时关单。

上述关单场景中，系统只发送最后一笔 transactionId 的 webhook，并在同一 payload 中同时返回 status 和 paymentStatus。

Webhook 重试机制：最多发送 3 次，间隔 30 分钟

Onerway 采用重试机制确保通知可靠送达：

首次通知：交易完成后，Onerway 立即发送 webhook 通知
响应验证：

✅ 商户正确响应（仅返回 transactionId 值，详见响应参数）：通知流程结束，不再重试
❌ 商户未正确响应（超时、错误响应、网络故障）：触发重试机制

重试策略：

重试次数：2 次
重试间隔：每次间隔 30 分钟
总计发送：最多 3 次（1 次首次通知 + 2 次重试）

重要提示

确保 webhook 接口具有幂等性（多次调用产生相同结果），能够正确处理重复通知
建议使用 transactionId 作为唯一标识进行去重处理

最佳实践

通知时间线示例：

时间点	动作	说明
T+0min	首次通知	交易完成后立即发送
T+30min	第一次重试	如商户未正确响应
T+60min	第二次重试	如商户仍未正确响应

验签规则

签名/验签统一规则

请求签名和 webhook 验签使用同一算法：ASCII 排序 -> 拼接 value -> 追加 secretKey -> SHA-256。
请求签名可按默认规则处理：仅剔除 sign，其余非空字段都参与签名（即 REQUEST_EXCLUDED_KEYS = ['sign']）。
webhook 验签场景必须按签名列为 No 的字段动态剔除，不要硬编码 Yes 白名单。
originTransactionId 按”默认参与”理解即可；只有在 webhook 验签时属于剔除字段。

webhook 不参与验签字段（当前）

'originTransactionId', 'originMerchantTxnId', 'customsDeclarationAmount', 'customsDeclarationCurrency', 'paymentMethod', 'walletTypeName', 'periodValue', 'tokenExpireTime', 'sign'

通知参数

Name	Type	Length	Signature	Description
notifyType	String	/	Yes	Notification type. See NotifyTypeEnum
txnType	String	/	Yes	Transaction type. See TxnTypeEnum Returned when `notifyType` is `TXN`
transactionId	String	20	Yes	Onerway transaction ID.
paymentId	String	/	Yes	Payment intent ID.
originTransactionId	String	20	No	Original transaction ID. Returned in reversal and dispute notifications
merchantTxnId	String	64	Yes	Merchant transaction ID.
originMerchantTxnId	String	64	No	Original merchant transaction ID. Returned in reversal notifications
merchantNo	String	20	Yes	Merchant number.
responseTime	String	/	Yes	Notification timestamp. Format: `yyyy-MM-dd HH:mm:ss`
txnTime	String	/	Yes	Transaction timestamp. Format: `yyyy-MM-dd HH:mm:ss`
txnTimeZone	String	/	Yes	Transaction timezone. Example: `+08:00`
orderAmount	String	19	Yes	Order amount.
orderCurrency	String	8	Yes	Order currency. See ISO 4217
txnAmount	String	19	Yes	Settlement amount.
txnCurrency	String	8	Yes	Settlement currency. See ISO 4217
settleRate	String	19	Yes	Exchange rate. Formula: `txnAmount = orderAmount × settleRate`
customsDeclarationAmount	String	19	No	Customs declarable amount.
customsDeclarationCurrency	String	8	No	Customs declaration currency. See ISO 4217
paymentMethod	String	64	No	Payment method.
walletTypeName	String	128	No	Digital wallet type.
status	String	1	Yes	Transaction status. Values: `S` - Success `F` - Failed/Declined/Rejected
paymentStatus	String	1	Yes	Payment intent status. See PaymentStatusEnum
reason	String	512	Yes	Status reason.
periodValue	String	/	No	Installment period.
contractId	String	20	Yes	Subscription contract ID.
tokenId	String	300	Yes	Payment token.
cardTokenId	String	300	Yes	Card token.
tokenExpireTime	String	/	No	Token expiration.
eci	String	2	Yes	ECI (Electronic Commerce Indicator).
chargebackDate	String	/	Yes	Chargeback date. Format: `yyyy-MM-dd`
importTime	String	/	Yes	Import timestamp. Format: `yyyy-MM-dd HH:mm:ss`
appealDueTime	String	/	Yes	Representment deadline. Format: `yyyy-MM-dd HH:mm:ss`
chargebackAmount	String	19	Yes	Dispute amount.
chargebackCurrency	String	8	Yes	Dispute currency. See ISO 4217
chargebackStatus	String	16	Yes	Dispute status. See ChargebackStatusEnum
chargebackArn	String	128	Yes	ARN (Acquirer Reference Number).
chargebackCode	String	32	Yes	Reason code.
chargebackReason	String	1024	Yes	Reason description.
cardBinCountry	String	64	Yes	Card issuing country. See ISO 3166
expireDate	String	/	Yes	Contract expiration. Format: `yyyy-MM-dd` Has value when `requestType` is `0`
subscriptionStatus	String	2048	Yes	Subscription status. See SubscriptionStatusEnum
dataStatus	String	2048	Yes	Contract status. See DataStatusEnum
products	String	1024	Yes	Product details.
subscriptionChangeTime	String	/	Yes	Effective date.
metaData	String	2048	Yes	Subscription custom metadata.
scenarios	String	2048	Yes	Subscription event. See ScenariosEnum
paymentMethodDetails	String	/	Yes	Payment method details in JSON string format. See PaymentMethodDetailsCard for structure.
sign	String	/	No	Signature. See the Signature documentation

webhook 验签代码示例

PHPJava

php

<?php

$webhookExcludedKeys = [
    'originTransactionId',
    'originMerchantTxnId',
    'customsDeclarationAmount',
    'customsDeclarationCurrency',
    'paymentMethod',
    'walletTypeName',
    'periodValue',
    'tokenExpireTime',
    'sign'
];

function buildCanonicalString(array $payload, array $excludedKeys): string
{
    ksort($payload, SORT_STRING);
    $canonicalString = '';

    foreach ($payload as $key => $value) {
        if (in_array($key, $excludedKeys, true)) {
            continue;
        }

        if ($value === null || $value === '') {
            continue;
        }

        $canonicalString .= (string) $value;
    }

    return $canonicalString;
}

function generateSignature(
    array $payload,
    string $secretKey,
    array $excludedKeys
): string {
    $canonicalString = buildCanonicalString($payload, $excludedKeys);
    return hash('sha256', $canonicalString . $secretKey);
}

function verifySignature(
    array $payload,
    string $secretKey,
    array $excludedKeys
): bool {
    $signature = (string) ($payload['sign'] ?? '');
    $computedSignature = generateSignature($payload, $secretKey, $excludedKeys);
    return hash_equals($computedSignature, $signature);
}

$payload = json_decode(file_get_contents('php://input'), true);
$secretKey = 'your-secret-key';

if (!verifySignature($payload, $secretKey, $webhookExcludedKeys)) {
    http_response_code(400);
    exit('invalid signature');
}

echo (string) $payload['transactionId'];

java

// 依赖: Spring Web (spring-boot-starter-web)
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.Map;
import java.util.Set;
import java.util.TreeMap;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;

@RestController
public class WebhookController {
  private static final Set<String> WEBHOOK_EXCLUDED_KEYS = Set.of(
      "originTransactionId",
      "originMerchantTxnId",
      "customsDeclarationAmount",
      "customsDeclarationCurrency",
      "paymentMethod",
      "walletTypeName",
      "periodValue",
      "tokenExpireTime",
      "sign"
  );

  @PostMapping("/webhook")
  public String webhook(@RequestBody Map<String, Object> payload) {
    String secretKey = "your-secret-key";
    boolean valid = verifySignature(payload, secretKey, WEBHOOK_EXCLUDED_KEYS);

    if (!valid) {
      throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Invalid signature");
    }

    return String.valueOf(payload.get("transactionId"));
  }

  public static String buildCanonicalString(
      Map<String, Object> payload,
      Set<String> excludedKeys
  ) {
    TreeMap<String, Object> sortedPayload = new TreeMap<>(payload);
    StringBuilder canonicalString = new StringBuilder();

    for (Map.Entry<String, Object> entry : sortedPayload.entrySet()) {
      if (excludedKeys.contains(entry.getKey())) {
        continue;
      }
      Object value = entry.getValue();
      if (value == null || "".equals(value)) {
        continue;
      }
      canonicalString.append(value);
    }

    return canonicalString.toString();
  }

  public static String generateSignature(
      Map<String, Object> payload,
      String secretKey,
      Set<String> excludedKeys
  ) {
    String dataToSign = buildCanonicalString(payload, excludedKeys) + secretKey;
    try {
      MessageDigest md = MessageDigest.getInstance("SHA-256");
      md.update(dataToSign.getBytes(StandardCharsets.UTF_8));
      return byte2Hex(md.digest());
    } catch (NoSuchAlgorithmException e) {
      throw new IllegalStateException("SHA-256 not available", e);
    }
  }

  public static boolean verifySignature(
      Map<String, Object> payload,
      String secretKey,
      Set<String> excludedKeys
  ) {
    String signature = String.valueOf(payload.getOrDefault("sign", ""));
    String computedSignature = generateSignature(payload, secretKey, excludedKeys);
    return computedSignature.equals(signature);
  }

  private static String byte2Hex(byte[] bytes) {
    StringBuilder sb = new StringBuilder();
    for (byte b : bytes) {
      sb.append(String.format("%02x", b & 0xFF));
    }
    return sb.toString();
  }
}

响应参数

仅返回 transactionId 的值，请勿包含其他参数或 JSON 结构

通知示例

支付成功

支付成功 - 卡支付支付成功 - ApplePay支付成功 - GooglePay

json

{
  "notifyType": "TXN", 
  "paymentId": "2031908578247712768", 
  "transactionId": "2028704543449423872",
  "txnType": "SALE", 
  "merchantNo": "800209",
  "merchantTxnId": "1b580d11-5d46-4a7a-995d-5c0d3df2f314",
  "responseTime": "2026-03-03 13:30:30",
  "txnTime": "2026-03-03 13:30:29",
  "txnTimeZone": "+08:00",
  "orderAmount": "10.00",
  "orderCurrency": "USD",
  "status": "S", 
  "paymentStatus": "S", 
  "cardBinCountry": "SG",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "b20de0b547d63c3b65c7aabb71eccff3e53184347e183ef675c157a3901ed6ea",
  "paymentMethod": "VISA", 
  "paymentMethodDetails": "{\"card\":{\"checks\":{\"addressCheck\":null,\"postalCodeCheck\":null,\"avsResultRawCode\":null,\"threeDSecureResult\":{\"version\":\"UNKNOWN\",\"authenticationFlow\":\"FRICTIONLESS\",\"chargebackLiability\":\"MERCHANT\",\"transStatus\":null,\"transStatusReason\":null,\"veresEnrolled\":null,\"eci\":\"05\",\"cvvResult\":null,\"avsFullResult\":null,\"cavvResult\":\"MjAyNi0wMy0wM1QxMzozMDozMC4zNjA=\"}},\"holderName\":\"CL BRW2\",\"year\":\"2026\",\"month\":\"05\",\"cardType\":null,\"productCategory\":null,\"issuer\":null,\"authorizationCode\":null,\"cardNumber\":\"476134******1390\"}}" // 卡信息（JSON 字符串格式，参与签名）
}

json

{
  "notifyType": "TXN", 
  "transactionId": "1925132987104890880",
  "txnType": "SALE", 
  "merchantNo": "800259",
  "merchantTxnId": "G_jN_p_xBdNWhrAE0Co6dQQ5whaYl1Oh07",
  "responseTime": "2025-05-21 18:14:23",
  "txnTime": "2025-05-21 18:14:06",
  "txnTimeZone": "+08:00",
  "orderAmount": "5.00",
  "orderCurrency": "USD",
  "status": "S",
  "cardBinCountry": "NZ",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "7bd1c8fd54c86873f7c9c70e77d968d5725ac85ccc8b6938f2c2dc74a0c917bd",
  "paymentMethod": "VISA", 
  "walletTypeName": "ApplePay", 
  "channelRequestId": "8002591925133054498705409"
}

json

{
  "notifyType": "TXN", 
  "transactionId": "2028706179144097792",
  "txnType": "SALE", 
  "merchantNo": "800209",
  "merchantTxnId": "0199407e-b2fa-4840-a396-213a8d631c88",
  "responseTime": "2026-03-03 13:37:41",
  "txnTime": "2026-03-03 13:36:59",
  "txnTimeZone": "+08:00",
  "orderAmount": "6.00",
  "orderCurrency": "USD",
  "status": "S",
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "d3cf989e6213422504f95d0ae45b59fdd25f98c7052d02dd22bae4186059f062",
  "paymentMethod": "VISA", 
  "paymentMethodDetails": "{\"card\":{\"checks\":null,\"holderName\":\"Fern Von\",\"year\":\"2028\",\"month\":\"12\",\"cardType\":null,\"productCategory\":null,\"issuer\":\"JPMORGAN CHASE BANK, N.A.\",\"authorizationCode\":null,\"cardNumber\":\"411111******1111\"}}", // 卡信息（JSON 字符串格式，参与签名）
  "walletTypeName": "GooglePay", 
  "channelRequestId": "8002092028706353840795649"
}

支付失败

json

{
  "notifyType": "TXN", 
  "paymentId": "2028705396700000000",
  "transactionId": "2028705396755406848",
  "txnType": "SALE", 
  "merchantNo": "800209",
  "merchantTxnId": "270377be-3f15-49a1-9949-32989ab56ebf",
  "responseTime": "2026-03-03 13:33:54",
  "txnTime": "2026-03-03 13:33:52",
  "txnTimeZone": "+08:00",
  "orderAmount": "10.00",
  "orderCurrency": "USD",
  "status": "F", 
  "paymentStatus": "O",
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"60005\",\"respMsg\":\"Do not honor\"}", 
  "sign": "d73aa59020b19b1990b0f1ef8cabf7968e216f16e6bae5c59dd17eb75b3602fb",
  "paymentMethod": "VISA", 
  "paymentMethodDetails": "{\"card\":{\"checks\":{\"addressCheck\":null,\"postalCodeCheck\":null,\"avsResultRawCode\":null,\"threeDSecureResult\":{\"version\":\"UNKNOWN\",\"authenticationFlow\":\"FRICTIONLESS\",\"chargebackLiability\":\"MERCHANT\",\"transStatus\":null,\"transStatusReason\":null,\"veresEnrolled\":null,\"eci\":\"05\",\"cvvResult\":null,\"avsFullResult\":null,\"cavvResult\":\"MjAyNi0wMy0wM1QxMzozMzo1My44MjI=\"}},\"holderName\":\"CL BRW2\",\"year\":\"2026\",\"month\":\"05\",\"cardType\":null,\"productCategory\":null,\"issuer\":\"NETSPEND\",\"authorizationCode\":null,\"cardNumber\":\"400012******8204\"}}", // 卡信息（JSON 字符串格式，参与签名）
  "channelRequestId": "8002092028705400517439489"
}

支付意图超时关闭（`paymentStatus = N`）

json

{
  "cardBinCountry": "US",
  "channelRequestId": "8006742031908579392495621",
  "merchantNo": "800674",
  "merchantTxnId": "PlBys270SR453lwcsnXTgL3pCykl879",
  "notifyType": "TXN",
  "orderAmount": "10.00",
  "orderCurrency": "USD",
  "paymentId": "2031908578247712768",
  "paymentMethod": "VISA",
  "paymentMethodDetails": "{\"card\":{\"checks\":{\"addressCheck\":\"notProvided\",\"postalCodeCheck\":\"notProvided\",\"avsResultRawCode\":null,\"threeDSecureResult\":null},\"holderName\":\"Evelyn Victorian\",\"year\":\"2030\",\"month\":\"11\",\"cardType\":null,\"productCategory\":null,\"issuer\":\"JPMORGAN CHASE BANK N.A. - DEBIT\",\"cardBinCountry\":\"US\",\"authorizationCode\":\"295859\",\"cardNumber\":\"442756******1274\"}}",
  "paymentStatus": "N",
  "reason": "{\"respCode\":\"60005\",\"respMsg\":\"Do not honor\"}",
  "responseTime": "2026-03-12 09:42:13",
  "sign": "b86b7c1b6e661b61ac1b7fa04e1fe3546a633ca574515bd9e92308b6eea24854",
  "status": "F",
  "transactionId": "2031908578310627328",
  "txnTime": "2026-03-12 09:42:10",
  "txnTimeZone": "+08:00",
  "txnType": "SALE"
}

Token 支付

绑卡Token 支付

json

{
  "notifyType": "TXN", 
  "transactionId": "1982651098431094784", // 绑卡交易 ID
  "txnType": "BIND_CARD", // 交易类型为 BIND_CARD
  "merchantNo": "800164",
  "merchantTxnId": "800164-1982651068391620608",
  "responseTime": "2025-10-27 11:30:33",
  "txnTime": "2025-10-27 11:30:32",
  "txnTimeZone": "+08:00",
  "orderAmount": "0.00", 
  "orderCurrency": "USD",
  "status": "S", 
  "tokenId": "d488be7426383edf4ce9c087ae47ebdfa2b58ecd462fdbf7eb841d5db04746f4", // 生成的 tokenId
  "tokenExpireTime": "2099-12-31 23:59:59", 
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "3e9ac7102fd9db939549bdadf50e8d85e85132db5cf67d36c44b520f77b32d35",
  "paymentMethod": "VISA",
  "channelRequestId": "002411"
}

json

{
  "notifyType": "TXN",
  "transactionId": "1921386970375127042",
  "txnType": "SALE", 
  "merchantNo": "800209",
  "merchantTxnId": "5ddbee02-908f-44f9-a7a8-ac1c391f00b5",
  "responseTime": "2025-05-11 10:09:02",
  "txnTime": "2025-05-11 10:08:46",
  "txnTimeZone": "+08:00",
  "orderAmount": "500.00",
  "orderCurrency": "USD",
  "status": "S", // 3DS 验证后的最终状态
  "tokenId": "f7d54297b989d2acf4eb6791213cf2bd9d2c842ea05b0a91c8dd85f4f9e4915b", 
  "eci": "05", // ECI 值表示 3DS 认证结果
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "5f654896436263215a0dea3798e67d5c714f3e54f57f9bf55fd08568db1d1b63",
  "paymentMethod": "VISA",
  "channelRequestId": "8002091921386975378677761"
}

订阅 - 首次扣款

托管订阅自管理订阅

json

{
  "notifyType": "TXN", 
  "transactionId": "1919772912060342272", 
  "txnType": "SALE", 
  "merchantNo": "800209",
  "merchantTxnId": "ec91ee2b-7ba9-444f-8875-955fe94fadf3",
  "responseTime": "2025-05-06 23:15:33",
  "txnTime": "2025-05-06 23:15:20",
  "txnTimeZone": "+08:00",
  "orderAmount": "2.00",
  "orderCurrency": "USD",
  "status": "S",
  "contractId": "1919772912228114432", 
  "tokenId": "195f7e75785863a66d3801ae02c12e24ea16abe164303cf3e3fd10e04d5e4188", 
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "6e8bd132b805c6ad530857331bef43c25e4c4a544dc2e0494cfd1ad94a7f55dc",
  "paymentMethod": "VISA",
  "subscriptionManageUrl": "https://sandbox-myscribe.onerway.com/pages/subscription-list/details?contractId=eyJjb250cmFjdElkIjoxOTE5NzcyOTEyMjI4MTE0NDMyLCJtZXJjaGFudE5vIjo4MDAyMDksIm1lcmNoYW50Q3VzdElkIjoiQ3VzdElkLUtYUlAtMzcxMSIsIm5vdGlmaWNhdGlvbkVtYWlsIjpudWxsLCJhcHBJZCI6IjE3Mjc4ODA4NDYzNzg0MDE3OTIifQ==", 
  "subscriptionStatus": "active", 
  "dataStatus": "1", 
  "products": "[{\"currency\":\"USD\",\"name\":\"currant\",\"num\":\"78\",\"price\":\"620.39\",\"type\":\"ullamco et do commodo ut\"},{\"currency\":\"USD\",\"name\":\"strawberry\",\"num\":\"63\",\"price\":\"289.61\",\"type\":\"labore cupidatat Duis elit\"},{\"currency\":\"USD\",\"name\":\"grapefruit\",\"num\":\"24\",\"price\":\"989.09\",\"type\":\"ullamco non\"}]",
  "metaData": "eventually",
  "channelRequestId": "8002091919772982323052544",
  "scenarios": "SUBSCRIPTION_INITIAL"
}

json

{
  "notifyType": "TXN", 
  "transactionId": "1914230281599320064", 
  "txnType": "SALE", 
  "merchantNo": "800209",
  "merchantTxnId": "8a4e276e-86c2-4753-b91a-0cc8881e4d0d",
  "responseTime": "2025-04-21 16:10:58",
  "txnTime": "2025-04-21 16:10:38",
  "txnTimeZone": "+08:00",
  "orderAmount": "33.00",
  "orderCurrency": "USD",
  "status": "S",
  "contractId": "1914230281792258048", 
  "tokenId": "7a83c22d55ca1e383fefbf1537c90b065a7324aee29a36d4b39c66da377a9b57", 
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "432894a2c697e01e4fe86eaa4f2564fb13ea97d0b4662a45fc83d1aa076985d1",
  "paymentMethod": "VISA",
  "subscriptionStatus": "active", 
  "dataStatus": "1", 
  "products": "[{\"currency\":\"USD\",\"name\":\"mandarin\",\"num\":\"47\",\"price\":\"234.19\",\"type\":\"eu dolore in\"}]",
  "metaData": "pfft",
  "channelRequestId": "8002091914230287013908481",
  "scenarios": "SUBSCRIPTION_INITIAL"
}

订阅 - 续费扣款

托管订阅 - 续费扣款托管订阅 - 套餐变更自管理订阅

json

{
  "notifyType": "TXN", 
  "transactionId": "1925220046993756162",
  "txnType": "SALE",
  "merchantNo": "800272",
  "merchantTxnId": "1925220044372316160",
  "responseTime": "2025-05-22 00:00:08",
  "txnTime": "2025-05-22 00:00:02",
  "txnTimeZone": "+08:00",
  "orderAmount": "0.95",
  "orderCurrency": "USD",
  "status": "S",
  "contractId": "1920300901562982400", 
  "tokenId": "a22e5904e7e6a7864947c216cd1169d2f1f12ff6663472cf1f4918b659106420", 
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "3d121d47adb826eb47f8aa8fd34d4ef8877990d5c529affb81e59b5340ba690c",
  "paymentMethod": "VISA",
  "subscriptionManageUrl": "https://sandbox-myscribe.onerway.com/pages/subscription-list/details?contractId=eyJjb250cmFjdElkIjoxOTIwMzAwOTAxNTYyOTgyNDAwLCJtZXJjaGFudE5vIjo4MDAyNzIsIm1lcmNoYW50Q3VzdElkIjoiNjc3NjVjYmIzYjJmNzRkZjQyODIwM2RlIiwibm90aWZpY2F0aW9uRW1haWwiOm51bGwsImFwcElkIjoiMTc5NjAwNzY3NDM4NDg3OTYxNiJ9", 
  "subscriptionStatus": "active", 
  "dataStatus": "1", 
  "products": "[{\"name\":\"Unlimited\",\"price\":\"0.95\",\"num\":\"1\",\"currency\":\"USD\"}]",
  "channelRequestId": "8002721925220051493982208",
  "scenarios": "SUBSCRIPTION_RENEWAL"
}

json

{
  "notifyType": "TXN", 
  "transactionId": "1920133309141491712",
  "txnType": "SALE",
  "merchantNo": "800209",
  "merchantTxnId": "d9de61b7-3480-48ed-90e6-4b0b9e2e4640",
  "responseTime": "2025-05-07 23:07:18",
  "txnTime": "2025-05-07 23:07:09",
  "txnTimeZone": "+08:00",
  "orderAmount": "20.00",
  "orderCurrency": "USD",
  "status": "S",
  "contractId": "1919772912228114432", 
  "tokenId": "195f7e75785863a66d3801ae02c12e24ea16abe164303cf3e3fd10e04d5e4188", 
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "cd220e77f9566e6cf20869c712c01dff34af9d0b52ffe2194510d88288827265",
  "paymentMethod": "VISA",
  "subscriptionManageUrl": "https://sandbox-myscribe.onerway.com/pages/subscription-list/details?contractId=eyJjb250cmFjdElkIjoxOTE5NzcyOTEyMjI4MTE0NDMyLCJtZXJjaGFudE5vIjo4MDAyMDksIm1lcmNoYW50Q3VzdElkIjoiQ3VzdElkLUtYUlAtMzcxMSIsIm5vdGlmaWNhdGlvbkVtYWlsIjpudWxsLCJhcHBJZCI6IjE3Mjc4ODA4NDYzNzg0MDE3OTIifQ==", 
  "subscriptionStatus": "active", 
  "dataStatus": "1", 
  "products": "[{\"name\":\"passionfruit\",\"desc\":null,\"price\":\"696.29\",\"num\":\"90\",\"currency\":\"USD\"},{\"name\":\"kiwiberry\",\"desc\":null,\"price\":\"948.79\",\"num\":\"36\",\"currency\":\"USD\"}]",
  "metaData": "eventually",
  "channelRequestId": "8002091920133320860106752",
  "scenarios": "SUBSCRIPTION_CHANGED"
}

json

{
  "notifyType": "TXN", 
  "transactionId": "1920061365985615872",
  "txnType": "SALE", 
  "merchantNo": "800209",
  "merchantTxnId": "6a28ac11-d98c-4323-84a7-426b9322c4f7",
  "responseTime": "2025-05-07 18:21:21",
  "txnTime": "2025-05-07 18:21:17",
  "txnTimeZone": "+08:00",
  "orderAmount": "2.00",
  "orderCurrency": "USD",
  "status": "S",
  "contractId": "1919781071080529920", 
  "tokenId": "b05d9de9836fe3e0dce5ba42078885cb90c729fe0604219a9cf24c092e71eb60", 
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "345f09b2240dcd2084605c28024b4d6fe7da4f84e59a7268b92bb66a36c433b3",
  "paymentMethod": "VISA",
  "subscriptionStatus": "active", 
  "dataStatus": "1", 
  "products": "[{\"currency\":\"USD\",\"name\":\"feijoa\",\"num\":\"88\",\"price\":\"968.79\",\"type\":\"consectetur adipisicing reprehenderit sint\"},{\"currency\":\"USD\",\"name\":\"avocado\",\"num\":\"52\",\"price\":\"414.89\",\"type\":\"consectetur labore\"}]",
  "metaData": "vary",
  "channelRequestId": "8002091920061371823816709",
  "scenarios": "SUBSCRIPTION_RENEWAL"
}

授权

授权扣款撤销/作废

json

{
  "notifyType": "TXN", 
  "transactionId": "1914565388776378368", // 扣款时需要作为 originTransactionId
  "txnType": "AUTH", 
  "merchantNo": "800209",
  "merchantTxnId": "4f581f27-fe1a-4a80-8e10-2b3751ffb785",
  "responseTime": "2025-04-22 14:22:51",
  "txnTime": "2025-04-22 14:22:42",
  "txnTimeZone": "+08:00",
  "orderAmount": "83.00",
  "orderCurrency": "USD",
  "status": "S",
  "eci": "05",
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "ec866293c15c4def1bad161c13f77153d560660065807612547d1c05a5de47bc",
  "paymentMethod": "VISA",
  "channelRequestId": "8002091914565512046706689"
}

json

{
  "notifyType": "TXN", 
  "transactionId": "1921486705937219584",
  "txnType": "CAPTURE", 
  "merchantNo": "800209",
  "merchantTxnId": "6b38115b-f2a2-446e-aaa7-7fbaa106adf4",
  "responseTime": "2025-05-11 16:50:01",
  "txnTime": "2025-05-11 16:45:05",
  "txnTimeZone": "+08:00",
  "orderAmount": "54.00",
  "orderCurrency": "USD",
  "status": "S", // 扣款完成的成功状态
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "74204385718b9327a8a3f3af03d16fd5130b2b9673277730aad4f627e2d32f19",
  "paymentMethod": "VISA",
  "channelRequestId": "8002091921486708126392321"
}

json

{
  "notifyType": "TXN", 
  "transactionId": "1921498535157956608",
  "txnType": "VOID", 
  "merchantNo": "800209",
  "merchantTxnId": "507df80b-243a-459b-bd76-bee35e7f0328",
  "responseTime": "2025-05-11 17:35:02",
  "txnTime": "2025-05-11 17:32:05",
  "txnTimeZone": "+08:00",
  "orderAmount": "10.00",
  "orderCurrency": "USD",
  "status": "S", // 撤销完成的成功状态
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "2fe73005baa11e3823a4b641393e2c7b79ee7d80b850c5185cdb3b11c6ee3170",
  "paymentMethod": "VISA",
  "channelRequestId": "8002091921498536260804609"
}

退款

json

{
  "notifyType": "TXN", 
  "transactionId": "1982640556668747776", 
  "txnType": "REFUND", 
  "merchantNo": "800256",
  "merchantTxnId": "1275019066607111",
  "originMerchantTxnId": "1275019066607111", 
  "responseTime": "2025-10-27 10:55:03",
  "txnTime": "2025-10-27 10:48:40",
  "txnTimeZone": "+08:00",
  "orderAmount": "100.00",
  "orderCurrency": "USD",
  "status": "S", 
  "cardBinCountry": "PL", 
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}", 
  "sign": "6f62d353d2abd843d34864a3ee78c03cec2eb8ba1713c62c5db5d748b6a44840",
  "paymentMethod": "VISA", 
  "channelRequestId": "8002561982640570996350977"
}

退款审核结果

json

{
  "notifyType": "REFUND_AUDIT", 
  "transactionId": "1925739837181530114",
  "merchantNo": "800209",
  "merchantTxnId": "R-b20e9b40-4479-4ab7-aa40-69463f7dea45",
  "originMerchantTxnId": "TX_zvKa3GX7_59496",
  "responseTime": "2025-05-23 10:26:06",
  "txnTimeZone": "+08:00",
  "orderAmount": "45.00",
  "orderCurrency": "USD",
  "status": "F", // F 表示失败/拒绝
  "sign": "d01abdaf733086272252ea1548644bef007e50aaa18329d737a8d103e5f4efa7"
}

拒付

json

{
  "notifyType": "CHARGEBACK", 
  "merchantNo": "800209",
  "transactionId": "1925859837858942976",
  "originTransactionId": "1925119888343830528", 
  "originMerchantTxnId": "TX_h2oS4AqU_51232",
  "importTime": "2025-05-23 18:22:20",
  "chargebackDate": "2025-05-23",
  "chargebackAmount": 1.0,
  "chargebackCurrency": "USD",
  "chargebackStatus": "NEW", 
  "chargebackArn": "0523",
  "chargebackCode": "123",
  "chargebackReason": "NOF",
  "appealReason": null,
  "appealDueTime": "2025-05-31 18:22:20",
  "sign": "6f2e6e180fa3f8f90985ac67e2f130fe59e6f8f4e5ad7d8ab56887fd6ef8704c"
}

收银台

下单

WebSDK

Android

绑卡支付

订阅支付

本地支付

Apple Pay

Google Pay

Ethoca

RDR

通知

注意事项

安全加固建议

IP 白名单限制

主动查询确认订单状态

Webhook 重试机制：最多发送 3 次，间隔 30 分钟

验签规则

通知参数

webhook 验签代码示例

响应参数

通知示例

支付成功

支付失败

支付意图超时关闭（`paymentStatus = N`）

Token 支付

订阅 - 首次扣款

订阅 - 续费扣款

授权

退款

退款审核结果

拒付

收银台

下单

WebSDK

Android

绑卡支付

订阅支付

本地支付

Apple Pay

Google Pay

通知 ​

注意事项 ​

安全加固建议 ​

IP 白名单限制 ​

主动查询确认订单状态 ​

Webhook 重试机制：最多发送 3 次，间隔 30 分钟 ​

验签规则 ​

通知参数 ​

webhook 验签代码示例 ​

响应参数 ​

通知示例 ​

支付成功 ​

支付失败 ​

支付意图超时关闭（paymentStatus = N） ​

Token 支付 ​

订阅 - 首次扣款 ​

订阅 - 续费扣款 ​

授权 ​

退款 ​

退款审核结果 ​

拒付 ​

通知

注意事项

安全加固建议

IP 白名单限制

主动查询确认订单状态

Webhook 重试机制：最多发送 3 次，间隔 30 分钟

验签规则

通知参数

webhook 验签代码示例

响应参数

通知示例

支付成功

支付失败

支付意图超时关闭（`paymentStatus = N`）

Token 支付

订阅 - 首次扣款

订阅 - 续费扣款

授权

退款

退款审核结果

拒付