Z Zise Developers
/
API 参考 › 沙盒
POST /v1/sandbox/upstream-behavior

沙盒 · 预置某家上游的返回行为

Scope merchant:read 商户自身 需 x-idempotency-key

⚠ 本期这个端点只写 KV，没有任何业务代码读它。

注入 timeout / unknown 之后，沙盒里的汇款、发卡、扫码付、提现

仍然打真实上游、仍然按真实结果返回。不要把它当作故障演练已经做过

—— 写在这里是因为「有 setter 没有 consumer」这件事，比一个不存在的

端点更容易让人误判：你会以为异常分支已经跑过一遍。

接线完成前，异常路径仍需靠沙盒上游自身的行为触发。

五档：success / reject / timeout / unknown / unknown_status。

unknown 是最要紧的一档 —— 它不是失败，是一个状态（网络层失败 /

超时 / 5xx）。你的代码若把它当失败去退款，在真实环境里会造成

「既退款又付款」，而那条路径在生产上一年也未必遇到一次。

注入 1 小时后自动回到 success（expires_in: 3600）—— 一个忘了

复位的注入会让你下一次联调拿到一堆莫名其妙的失败。

注入按 (商户, 上游) 隔离，两个沙盒商户之间互不影响。

字段类型必填说明
x-idempotency-key string 必填 UUID v4

请求体

字段类型必填说明
upstream "uqpay" | "photonpay" | "paydify" | "cobo" 必填 哪一家上游。大小写不敏感；认不出回 invalid_request
behavior "success" | "reject" | "timeout" | "unknown" | "unknown_status" 必填 预置成什么。unknown = 结果不明（不是失败）； unknown_status = 上游回了一个我方枚举里没有的状态。

响应

200已注入
{
  "ok": true,
  "upstream": "uqpay",
  "behavior": "unknown",
  "expires_in": 3600
}
400invalid_request body 非 JSON / upstream 或 behavior 不在枚举内
404不在沙盒环境
调用样例 
curl -X POST 'https://api.zise.com/v1/sandbox/upstream-behavior' \
  -H 'authorization: Bearer $TOKEN' \
  -H 'x-zise-merchant: $MERCHANT_ID' \
  -H 'x-idempotency-key: $(uuidgen)' \
  -H 'content-type: application/json' \
  -d '{
    "upstream": "uqpay",
    "behavior": "unknown"
  }'
const res = await fetch(
  "https://api.zise.com/v1/sandbox/upstream-behavior",
  {
    method: "POST",
    headers: {
      "authorization": "Bearer $TOKEN",
      "x-zise-merchant": "MERCHANT_ID",
      "x-idempotency-key": "crypto.randomUUID()",
      "content-type": "application/json"
    },
    body: JSON.stringify({
      "upstream": "uqpay",
      "behavior": "unknown"
    }),
  },
);
// 金额一律按字符串读，不要 JSON.parse 成 number
const data = await res.json();
import requests

res = requests.post(
    "https://api.zise.com/v1/sandbox/upstream-behavior",
    headers={
        "authorization": "Bearer $TOKEN",
        "x-zise-merchant": "$MERCHANT_ID",
        "x-idempotency-key": "$(uuidgen)",
        "content-type": "application/json"
    },
    json={
        "upstream": "uqpay",
        "behavior": "unknown"
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()