对接准备

对接准备

确定接入方式后，请联系Soobey团队获得测试参数。

按接入方式准备

通用规范

协议、金额与签名

公共报文规则只适用于对应协议。云端 API、POS LAN 与 AIDL 的字段和状态不可混用。

云端公共请求参数

云端公共响应参数

云端请求签名

按原文签名章节：req_ver、app_id、sign_type、req_time、req_id、req_params 参与签名；encrypt_type 非空时加入。按字段名 ASCII 升序排列，以 & 连接 k=v，使用 UTF-8 和商户私钥进行 RSA2 签名。isv_code、terminal_no、key_sign 不参与。

req_params = JSON.stringify(business)
fields = pick(request, ["req_ver", "app_id", "sign_type", "req_time", "req_id", "req_params"])
if (request.encrypt_type is nonempty): fields.encrypt_type = request.encrypt_type
canonical = join(sortKeysAscii(fields).map(key => key + "=" + fields[key]), "&")
key_sign = rsa2SignUtf8(canonical, merchantPrivateKey)
// Preserve req_params exactly. Do not parse/reformat it after signing.

不要把请求编号当作防重复扣款保证

云端原文说明 req_id 不做强校验，主要用于日志；CPM 的 merchant_order_no 也明确不验重。超时或结果未知时保留原交易标识，先查询／对账，不直接重发扣款或退款。

云端支付 API

云端 API：由商户服务端调用

先完成公共签名，再按支付场景选择一个创建接口。订单查询、退款与撤销使用原交易标识，不是再次创建支付。

{
  "req_ver": "1.0",
  "app_id": "YOUR_APP_ID",
  "isv_code": "YOUR_ISV",
  "sign_type": "RSA2",
  "req_time": "CURRENT_EPOCH_MS",
  "req_id": "UNIQUE_REQUEST_ID",
  "req_params": "{\"pay_ver\":\"100\",\"merchant_no\": \"YOUR_MERCHANT\",\"merchant_order_no\":\"ORDER-001\",\"pay_type\":\"5\",\"total_fee\":\"1280\",\"terminal_time\":\"20261009120000\",\"auth_no\":\"TEST_PAYMENT_CODE\",\"currency\":\"HKD\",\"notify_url\":\"https://merchant.example/notify\",\"time_expire\":\"600\"}",
  "key_sign": "EXAMPLE_SIGNATURE"
}

{
  "resp_code": "10000",
  "resp_msg": "Example only",
  "resp_params": "{\"merchant_no\": \"YOUR_MERCHANT\",\"merchant_name\":\"Example merchant\",\"merchant_order_no\":\"ORDER-001\",\"out_trade_no\":\"EXAMPLE-PLATFORM-ORDER\",\"order_state\":\"PAYSUCCESS\",\"total_fee\":\"1280\"}",
  "key_sign": "EXAMPLE_SIGNATURE"
}

business = buildBusinessParams() // use this endpoint's field table
payload = JSON.stringify(business) // serialize once; preserve the exact string
request = buildEnvelope(payload, currentEpochMs(), newRequestId())
request.key_sign = signRsa2(canonicalRequestFields(request), merchantPrivateKey)
response = POST(baseUrl + "/open/payment/barcodepay", request)
if (networkError || signatureError): keepPendingAndQueryOriginalOrder()
else:
    verifySignedCloudResponse(response)
    if (response.resp_code != "10000"): handleEnvelopeErrorWithoutAssumingPaymentFailed()
    else: result = JSON.parse(response.resp_params)
if (result.order_state == "PAYSUCCESS"): markPaidOnce()
else: applyEndpointStatePolicy(result.order_state)

{
  "req_ver": "1.0",
  "app_id": "YOUR_APP_ID",
  "isv_code": "YOUR_ISV",
  "sign_type": "RSA2",
  "req_time": "CURRENT_EPOCH_MS",
  "req_id": "UNIQUE_REQUEST_ID",
  "req_params": "{\"pay_ver\":\"100\",\"merchant_no\": \"YOUR_MERCHANT\",\"merchant_order_no\":\"ORDER-001\",\"pay_type\":\"5\",\"total_fee\":\"1280\",\"terminal_ip\":\"192.0.2.10\",\"currency\":\"HKD\",\"notify_url\":\"https://merchant.example/notify\",\"time_expire\":\"600\"}",
  "key_sign": "EXAMPLE_SIGNATURE"
}

{
  "resp_code": "10000",
  "resp_msg": "Example only",
  "resp_params": "{\"merchant_no\": \"YOUR_MERCHANT\",\"merchant_name\":\"Example merchant\",\"merchant_order_no\":\"ORDER-001\",\"out_trade_no\":\"EXAMPLE-PLATFORM-ORDER\",\"pre_order_state\":\"SUCCESS\",\"qr_code\":\"EXAMPLE_QR_PAYLOAD\"}",
  "key_sign": "EXAMPLE_SIGNATURE"
}

business = buildBusinessParams() // use this endpoint's field table
payload = JSON.stringify(business) // serialize once; preserve the exact string
request = buildEnvelope(payload, currentEpochMs(), newRequestId())
request.key_sign = signRsa2(canonicalRequestFields(request), merchantPrivateKey)
response = POST(baseUrl + "/open/payment/prepay", request)
if (networkError || signatureError): keepPendingAndQueryOriginalOrder()
else:
    verifySignedCloudResponse(response)
    if (response.resp_code != "10000"): handleEnvelopeErrorWithoutAssumingPaymentFailed()
    else: result = JSON.parse(response.resp_params)
if (result.pre_order_state == "SUCCESS"):
    displayQr(result.qr_code)
    confirmWithQueryOrVerifiedWebhook() // creation/client return is not payment success

{
  "req_ver": "1.0",
  "app_id": "YOUR_APP_ID",
  "isv_code": "YOUR_ISV",
  "sign_type": "RSA2",
  "req_time": "CURRENT_EPOCH_MS",
  "req_id": "UNIQUE_REQUEST_ID",
  "req_params": "{\"pay_ver\":\"100\",\"merchant_no\": \"YOUR_MERCHANT\",\"merchant_order_no\":\"ORDER-001\",\"pay_type\":\"4\",\"total_fee\":\"1280\",\"terminal_ip\":\"192.0.2.10\",\"currency\":\"HKD\",\"notify_url\":\"https://merchant.example/notify\",\"time_expire\":\"600\"}",
  "key_sign": "EXAMPLE_SIGNATURE"
}

{
  "resp_code": "10000",
  "resp_msg": "Example only",
  "resp_params": "{\"merchant_no\": \"YOUR_MERCHANT\",\"merchant_name\":\"Example merchant\",\"merchant_order_no\":\"ORDER-001\",\"out_trade_no\":\"EXAMPLE-PLATFORM-ORDER\",\"pre_order_state\":\"SUCCESS\",\"appId\":\"EXAMPLE_APP\",\"timeStamp\":\"1791518400\",\"nonceStr\":\"EXAMPLE_NONCE\",\"package_str\":\"prepay_id=EXAMPLE\",\"signType\":\"RSA\",\"paySign\": \"EXAMPLE_SIGNATURE\"}",
  "key_sign": "EXAMPLE_SIGNATURE"
}

business = buildBusinessParams() // use this endpoint's field table
payload = JSON.stringify(business) // serialize once; preserve the exact string
request = buildEnvelope(payload, currentEpochMs(), newRequestId())
request.key_sign = signRsa2(canonicalRequestFields(request), merchantPrivateKey)
response = POST(baseUrl + "/open/payment/jspay", request)
if (networkError || signatureError): keepPendingAndQueryOriginalOrder()
else:
    verifySignedCloudResponse(response)
    if (response.resp_code != "10000"): handleEnvelopeErrorWithoutAssumingPaymentFailed()
    else: result = JSON.parse(response.resp_params)
if (result.pre_order_state == "SUCCESS"):
    invokeWalletClientPayment(result)
    confirmWithQueryOrVerifiedWebhook() // creation/client return is not payment success

{
  "req_ver": "1.0",
  "app_id": "YOUR_APP_ID",
  "isv_code": "YOUR_ISV",
  "sign_type": "RSA2",
  "req_time": "CURRENT_EPOCH_MS",
  "req_id": "UNIQUE_REQUEST_ID",
  "req_params": "{\"pay_ver\":\"100\",\"merchant_no\": \"YOUR_MERCHANT\",\"merchant_order_no\":\"ORDER-001\",\"pay_type\":\"4\",\"total_fee\":\"1280\",\"terminal_ip\":\"192.0.2.10\",\"openid\": \"YOUR_OPENID\",\"currency\":\"HKD\",\"notify_url\":\"https://merchant.example/notify\",\"time_expire\":\"600\"}",
  "key_sign": "EXAMPLE_SIGNATURE"
}

{
  "resp_code": "10000",
  "resp_msg": "Example only",
  "resp_params": "{\"merchant_no\": \"YOUR_MERCHANT\",\"merchant_name\":\"Example merchant\",\"merchant_order_no\":\"ORDER-001\",\"out_trade_no\":\"EXAMPLE-PLATFORM-ORDER\",\"pre_order_state\":\"SUCCESS\",\"appId\":\"EXAMPLE_APP\",\"timeStamp\":\"1791518400\",\"nonceStr\":\"EXAMPLE_NONCE\",\"package_str\":\"prepay_id=EXAMPLE\",\"signType\":\"RSA\",\"paySign\": \"EXAMPLE_SIGNATURE\"}",
  "key_sign": "EXAMPLE_SIGNATURE"
}

business = buildBusinessParams() // use this endpoint's field table
payload = JSON.stringify(business) // serialize once; preserve the exact string
request = buildEnvelope(payload, currentEpochMs(), newRequestId())
request.key_sign = signRsa2(canonicalRequestFields(request), merchantPrivateKey)
response = POST(baseUrl + "/open/payment/minipay", request)
if (networkError || signatureError): keepPendingAndQueryOriginalOrder()
else:
    verifySignedCloudResponse(response)
    if (response.resp_code != "10000"): handleEnvelopeErrorWithoutAssumingPaymentFailed()
    else: result = JSON.parse(response.resp_params)
if (result.pre_order_state == "SUCCESS"):
    invokeWalletClientPayment(result)
    confirmWithQueryOrVerifiedWebhook() // creation/client return is not payment success

{
  "req_ver": "1.0",
  "app_id": "YOUR_APP_ID",
  "isv_code": "YOUR_ISV",
  "sign_type": "RSA2",
  "req_time": "CURRENT_EPOCH_MS",
  "req_id": "UNIQUE_REQUEST_ID",
  "req_params": "{\"pay_ver\":\"100\",\"merchant_no\": \"YOUR_MERCHANT\",\"merchant_order_no\":\"ORDER-001\",\"pay_type\":\"5\",\"total_fee\":\"1280\",\"terminal_ip\":\"192.0.2.10\",\"currency\":\"HKD\",\"notify_url\":\"https://merchant.example/notify\",\"time_expire\":\"600\"}",
  "key_sign": "EXAMPLE_SIGNATURE"
}

{
  "resp_code": "10000",
  "resp_msg": "Example only",
  "resp_params": "{\"merchant_no\": \"YOUR_MERCHANT\",\"merchant_name\":\"Example merchant\",\"merchant_order_no\":\"ORDER-001\",\"out_trade_no\":\"EXAMPLE-PLATFORM-ORDER\",\"pre_order_state\":\"SUCCESS\",\"pay_url\":\"https://example.invalid/payment\"}",
  "key_sign": "EXAMPLE_SIGNATURE"
}

business = buildBusinessParams() // use this endpoint's field table
payload = JSON.stringify(business) // serialize once; preserve the exact string
request = buildEnvelope(payload, currentEpochMs(), newRequestId())
request.key_sign = signRsa2(canonicalRequestFields(request), merchantPrivateKey)
response = POST(baseUrl + "/open/payment/wappay", request)
if (networkError || signatureError): keepPendingAndQueryOriginalOrder()
else:
    verifySignedCloudResponse(response)
    if (response.resp_code != "10000"): handleEnvelopeErrorWithoutAssumingPaymentFailed()
    else: result = JSON.parse(response.resp_params)
if (result.pre_order_state == "SUCCESS"):
    redirectCustomer(result.pay_url)
    confirmWithQueryOrVerifiedWebhook() // creation/client return is not payment success

{
  "req_ver": "1.0",
  "app_id": "YOUR_APP_ID",
  "isv_code": "YOUR_ISV",
  "sign_type": "RSA2",
  "req_time": "CURRENT_EPOCH_MS",
  "req_id": "UNIQUE_REQUEST_ID",
  "req_params": "{\"pay_ver\":\"100\",\"merchant_no\": \"YOUR_MERCHANT\",\"out_trade_no\":\"ORIGINAL_PLATFORM_ORDER\"}",
  "key_sign": "EXAMPLE_SIGNATURE"
}

{
  "resp_code": "10000",
  "resp_msg": "Example only",
  "resp_params": "{\"merchant_no\": \"YOUR_MERCHANT\",\"merchant_name\":\"Example merchant\",\"merchant_order_no\":\"ORDER-001\",\"out_trade_no\":\"EXAMPLE-PLATFORM-ORDER\",\"order_state\":\"PAYSUCCESS\",\"total_fee\":\"1280\"}",
  "key_sign": "EXAMPLE_SIGNATURE"
}

business = buildBusinessParams() // use this endpoint's field table
payload = JSON.stringify(business) // serialize once; preserve the exact string
request = buildEnvelope(payload, currentEpochMs(), newRequestId())
request.key_sign = signRsa2(canonicalRequestFields(request), merchantPrivateKey)
response = POST(baseUrl + "/open/payment/query", request)
if (networkError || signatureError): keepPendingAndQueryOriginalOrder()
else:
    verifySignedCloudResponse(response)
    if (response.resp_code != "10000"): handleEnvelopeErrorWithoutAssumingPaymentFailed()
    else: result = JSON.parse(response.resp_params)
if (result.order_state == "PAYSUCCESS"): markPaidOnce()
else: applyEndpointStatePolicy(result.order_state)

{
  "req_ver": "1.0",
  "app_id": "YOUR_APP_ID",
  "isv_code": "YOUR_ISV",
  "sign_type": "RSA2",
  "req_time": "CURRENT_EPOCH_MS",
  "req_id": "UNIQUE_REQUEST_ID",
  "req_params": "{\"pay_ver\":\"100\",\"merchant_no\": \"YOUR_MERCHANT\",\"out_trade_no\":\"ORIGINAL_PLATFORM_ORDER\",\"refund_fee\":\"1280\"}",
  "key_sign": "EXAMPLE_SIGNATURE"
}

{
  "resp_code": "10000",
  "resp_msg": "Example only",
  "resp_params": "{\"merchant_no\": \"YOUR_MERCHANT\",\"merchant_name\":\"Example merchant\",\"merchant_order_no\":\"ORDER-001\",\"out_trade_no\":\"EXAMPLE-PLATFORM-ORDER\",\"order_state\":\"REFUNDSUCCESS\",\"refund_fee\":\"1280\",\"out_refund_no\":\"EXAMPLE-REFUND\"}",
  "key_sign": "EXAMPLE_SIGNATURE"
}

business = buildBusinessParams() // use this endpoint's field table
payload = JSON.stringify(business) // serialize once; preserve the exact string
request = buildEnvelope(payload, currentEpochMs(), newRequestId())
request.key_sign = signRsa2(canonicalRequestFields(request), merchantPrivateKey)
response = POST(baseUrl + "/open/payment/refund", request)
if (networkError || signatureError): keepPendingAndQueryOriginalOrder()
else:
    verifySignedCloudResponse(response)
    if (response.resp_code != "10000"): handleEnvelopeErrorWithoutAssumingPaymentFailed()
    else: result = JSON.parse(response.resp_params)
if (result.order_state == "REFUNDSUCCESS"): recordRefundOnce(result.out_refund_no)
else: keepRefundPendingUntilConfirmed() // do not blindly resubmit refund

{
  "req_ver": "1.0",
  "app_id": "YOUR_APP_ID",
  "isv_code": "YOUR_ISV",
  "sign_type": "RSA2",
  "req_time": "CURRENT_EPOCH_MS",
  "req_id": "UNIQUE_REQUEST_ID",
  "req_params": "{\"pay_ver\":\"100\",\"merchant_no\": \"YOUR_MERCHANT\",\"out_trade_no\":\"ORIGINAL_PLATFORM_ORDER\"}",
  "key_sign": "EXAMPLE_SIGNATURE"
}

{
  "resp_code": "10000",
  "resp_msg": "Example only",
  "resp_params": "{\"merchant_no\": \"YOUR_MERCHANT\",\"merchant_name\":\"Example merchant\",\"merchant_order_no\":\"ORDER-001\",\"out_trade_no\":\"EXAMPLE-PLATFORM-ORDER\",\"order_state\":\"CANCELSUCCESS\"}",
  "key_sign": "EXAMPLE_SIGNATURE"
}

business = buildBusinessParams() // use this endpoint's field table
payload = JSON.stringify(business) // serialize once; preserve the exact string
request = buildEnvelope(payload, currentEpochMs(), newRequestId())
request.key_sign = signRsa2(canonicalRequestFields(request), merchantPrivateKey)
response = POST(baseUrl + "/open/payment/cancel", request)
if (networkError || signatureError): keepPendingAndQueryOriginalOrder()
else:
    verifySignedCloudResponse(response)
    if (response.resp_code != "10000"): handleEnvelopeErrorWithoutAssumingPaymentFailed()
    else: result = JSON.parse(response.resp_params)
if (result.order_state == "CANCELSUCCESS"): recordCancellation()
else: queryOriginalOrderBeforeAnyNewPayment()

按支付场景接入

创建订单成功、浏览器回跳和客户端支付回调均不能单独作为服务端入账依据。字段及状态以对应接口为准。

POS 终端协议 · 3.0

POS 终端协议：三种模式，分别对接

先看你的业务系统在哪里运行、由谁展示支付界面，再选择接入模式。云推、局域网和 AIDL 的连接方式不同，各自对应一套接口和处理流程。

云端推送

云推模式：服务端远程触发 POS

商户后台创建订单后，通过平台接口把收款任务发送到指定 POS 或已绑定的终端。支付结果再用查询接口确认；退款也以任务形式发送到 POS。

// Pseudocode — sign the request using the Cloud API common spec
order = {
  send_mode: 1,                 // 1: target terminal; 2: bound terminal
  to_terminal_no: "POS-001",
  terminal_trace: "T202610060001",
  total_fee: "1280",
  expiration_time: "180"
}
pushResult = await POST("open/order/sendPrePay", sign(order))
if pushResult.accepted:
    status = await queryByOutTradeNo(pushResult.out_trade_no)
    if status.pay_status_code == "3":
        reconcileOriginalOrder() // do not create another charge

局域网收银

局域网收银：收银机直连 POS

收银机和 POS 接入同一局域网后，收银机可直接调用 POS。支付或退款界面由 POS 展示，收银机等待同步响应；如果网络中断或 POS 没有响应，先查原订单，不要马上重试扣款。

核心业务字段

响应字段与验签

// Pseudocode — keep the business idempotency key; refresh req_id per HTTP attempt
businessKey = terminalTrace + "|" + terminalTime
result = await sendSignedPosRequest({
  req_id: newUniqueRequestId(),
  req_params: { terminal_trace: terminalTrace, terminal_time: terminalTime, total_fee: amountMinor }
})
if (result.pay_status_code == "3" || responseWasLost):
    result = await queryOriginalOrder(terminalTrace, terminalTime)
if (result.pay_status_code == "1"): markPaid()
else if (result.pay_status_code == "2" || result.pay_status_code == "4"): markFinal(result)
else: keepPendingAndReconcile(businessKey) // never charge again while unknown

SDK / Android AIDL · SoftPOS

SDK / AIDL：同机应用调用 POS 服务（计划中）

如果你的业务应用和 Soobey POS 安装在同一台 Android 终端，就可以通过 AIDL 调用 POS 服务。支付界面和扫码由 POS 负责；这条接入方式不调用云端 HTTPS API。

Service 方法

请求与返回对象

状态机与 PendingIntent

ACCEPTED → BOOTSTRAPPING → READY → WAITING_FOR_UI → PROCESSING
                              │          │                 ├→ SUCCESS
                              │          └→ CANCELED       ├→ FAILED
               └→ BOOTSTRAP_FAILED          └→ UNKNOWN

SUCCESS / FAILED / CANCELED / BOOTSTRAP_FAILED = terminal states
UNKNOWN = outcome not confirmed; queryPayment(sessionId), never assume failure

收到 WAITING_FOR_UI 后，请让处于前台的 App 发送一次性 uiPendingIntent，以打开 POS 支付页。Android 10 及以上版本不要从后台 Service 直接调用 startActivity。

// Pseudocode based on the AIDL contract
intent = Intent("com.soobey.pos.external.action.PAYMENT_SERVICE")
intent.setPackage("com.soobey.pos")
bindService(intent)
if (service.getReadiness().state != "READY"): stopAndShowReadinessReason()
accepted = service.createPayment(request, callback)
if (!accepted.accepted): handleAcceptanceError(accepted.errorCode)
else:
    persist(accepted.sessionId)
    onStateChanged(snapshot):
        if (snapshot.status == "WAITING_FOR_UI"): sendFromForeground(snapshot.uiPendingIntent)
        if (snapshot.status == "UNKNOWN"): queryPayment(snapshot.sessionId)
        if (snapshot.status in ["SUCCESS", "FAILED", "CANCELED", "BOOTSTRAP_FAILED"]): updateOrderIdempotently(snapshot)
// On Binder death / process restart, reconnect and query the stored sessionId.

回调通知

回调通知：服务端确认支付结果

云端支付 API 会把支付和退款结果异步发送到 notify_url。接收后先验签，再按业务标识幂等处理，最后返回应答。

回调外层字段

// Pseudocode: keep envelope fields separate from business fields
envelope = parseJson(rawRequest)
if (!verifyCallback(envelope, platformPublicKey)): return { return_code: "02" }
payload = envelope.req_params // original signed string
if (envelope.encrypt_type == "AES"): payload = decryptWithConfirmedAesConfig(payload)
event = parseJson(payload)
if (!matchesMerchantAndOriginalOrder(event)): persistForReview(); return { return_code: "02" }
if (event.order_state == "REFUNDSUCCESS" && !stableRefundReferenceConfirmed(event)):
    persistForReconciliation(event); return { return_code: "02" }
transaction:
    key = stableBusinessEventKey(event) // payment reference, or confirmed refund reference
    if (!alreadyProcessed(key)):
        applyPaymentOrRefundState(event)
        recordProcessed(key)
return { return_code: "01", return_msg: "success" }
// Complete persistence/processing before ACK; respond within 5 seconds.

错误码与排查

错误码与排查：按接口族解释

同一个错误码在不同接口里可能代表不同问题。先确认请求走的是哪种接入方式，再按对应表格排查。

云端 API · 系统级错误码

POS LAN · resp_code

通道与市场支持

通道与市场支持

具体商户能使用哪些渠道、币种和钱包，请以商户开通配置为准。

联调、验收与上线

联调、验收与上线

按你实际采用的接入方式完成联调和验收。必测项和端到端流程都通过，并经双方确认后，再切换到生产环境。

切生产前清单

关键验收用例

以下按当前接入方式展示关键验收用例。请按对应接口的字段表准备测试报文。