Sandbox: simulate an incoming upstream card transaction

Available only in the sandbox; returns 404 in live mode. Only card products with transaction simulation support are eligible. Unsupported cards return product_not_available without writing transactions or callback inbox entries.

── Why this endpoint is necessary ──

/v1/sandbox/upstream-behavior injects behavior into our outbound upstream call. Card purchases, refunds, reversals, settlements, and chargebacks are instead pushed to us by the upstream, with no outbound call on this path, so such injection is a no-op here. Sandbox cards also cannot make real purchases because there is no acquiring side. Without this endpoint, all your card-transaction handling code for posting, reconciliation, limit recovery, and chargeback disputes would go live without ever running, and its first real execution would involve real money in production. This endpoint moves that first execution into the sandbox.

── The payload follows the real processing path ──

We construct an upstream-shaped callback and feed it through the exact production pipeline: inbox deduplication → normalization → direction determination → posting only on succeed → ledger → limits → risk counters → penalties/card freezing. Only signature verification is skipped, because we do not have the upstream's private key. A simulation that merely inserts a transaction row would bypass every one of these steps and produce a misleading pass.

── Where to observe results ──

Simulated and normal card-transaction callbacks share the same processing path. Once persisted, they emit card.transaction.updated with object card_transaction, a ctx_ transaction ID, a crd_ card ID, and the actual status. Query transaction details through the transaction list after receiving it. Inspect three places:

• GET /v1/cards/{id}/transactions: the new transaction row. **Also read direction**, because amount is absolute; auth_code matches the value in this response.
• GET /v1/cards/{id}: changes to balance and limits.
• The card.status.updated event: when repeated chargeback scenarios exceed the freeze threshold, this event is actually delivered. It is the only event pushed to you on this line.

── Repeated scenarios ──

repeat runs the same scenario N times, up to 20, to exceed free-event allowances and freeze thresholds (the chargeback threshold is 3). Each transaction uses a different transaction ID. Reusing an ID triggers inbox deduplication, and a single counted event could be mistaken for risk controls not working.

── Transaction IDs ──

txn_id applies only when repeat is omitted or 1. We prepend the merchant identifier (SBX-<你的沙盒商户号>-<你给的值>) before using it. This is necessary because transaction-ID deduplication is database-wide: unrestricted IDs could claim another merchant's identifier, causing their transaction to be silently treated as a duplicate.

── Insufficient balance ──

Our ledger rejects the transaction and returns insufficient_balance, including completed, the number of earlier transactions in this batch already processed. This is not a platform failure; it reminds you that a real upstream would send a decline rather than a successful authorization in this situation. Use the decline_insufficient scenario to test that branch.

Prerequisites

• The current token resolves to a sandbox shadow entity; live credentials always return 404.
• The card belongs to this member and merchant and already has an upstream card identifier.

Path Parameters

Request Headers

Request Body

Response

{
  "card_id": "crd_2c9e4b10-77af-4d3a-8e51-b0d6c2f9a134",
  "scenario": "auth_ok",
  "expect": "过⑤号凭证 · 已使用额度 +金额 · 可用额度 −金额 · 不计风控",
  "events": [
    {
      "txn_id": "SBX-acme_sbx-9F2C7A1B4D6E8035",
      "auth_code": "6E8035",
      "deduplicated": false
    }
  ],
  "note": "载荷经与生产逐字相同的回调管线落地（含收件箱去重），只跳过验签。"
}

Emitted Events

Green = successful terminal state · Red = terminal state requiring action · Purple = intermediate state. Open an event for its payload and signature verification details.