沙箱測試

沙箱使用與正式環境相同的 API 主機。沙箱 API 金鑰會選擇測試環境,其中的輔助工具可模擬結果而不移動實際資金。請將金鑰保存在後端。沙箱輔助工具不會取代正式環境的法遵或入駐流程。

export API_BASE='https://platform.swipelux.com'
export SWIPELUX_SANDBOX_API_KEY='replace-with-your-sandbox-key'

測試能力就緒

在申請能力之後,使用 POST /v3/sandbox/customers/{customerId}/capabilities/{capabilityId}/status 設定其沙箱狀態:

curl --request POST \
  "${API_BASE}/v3/sandbox/customers/${CUSTOMER_ID}/capabilities/${CAPABILITY_ID}/status" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{"status":"ready"}'

使用輔助工具後請重新讀取該能力。請將其當前的 status 與 openTaskIds 視為您的產品必須處理的結果。

測試待辦任務

使用 POST /v3/sandbox/tasks 建立沙箱任務。將任務限定到您正在測試其工作流程的資源,並使用 items 描述客戶必須提交的內容。本指南示範能力與轉帳工作流程;API 參考定義客戶範圍及完整的請求結構。文字答覆使用 explanation 項目,檔案上傳使用 document 項目。新的 profile 項目還必須提供 profilePointer,也就是指向客戶欄位的 JSON Pointer。其他項目類型與欄位請參閱建立沙箱任務。在轉帳範例中,請先透過收款或付款流程建立沙箱轉帳,然後匯出回傳的 data.id:

export TRANSFER_ID='tr_replace_with_your_transfer_id'

能力 + 說明
轉帳 RFI + 文件

curl --request POST \
  "${API_BASE}/v3/sandbox/tasks" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
  "scope": {
    "type": "capability",
    "customerId": "${CUSTOMER_ID}",
    "capabilityId": "${CAPABILITY_ID}"
  },
  "items": [
    {
      "type": "explanation",
      "request": "Explain the source of funds."
    }
  ]
}
JSON

將任務範圍設定為審查中的轉帳,並透過 constraints 縮小可接受的類型、格式與時效,請求提供文件。

curl --request POST \
  "${API_BASE}/v3/sandbox/tasks" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
  "scope": {
    "type": "transfer",
    "customerId": "${CUSTOMER_ID}",
    "transferId": "${TRANSFER_ID}"
  },
  "category": "transaction_rfi",
  "items": [
    {
      "type": "document",
      "request": "Upload a bank statement showing the source of funds for this transfer.",
      "constraints": {
        "acceptedDocumentTypes": ["bank_statement"],
        "acceptedFormats": ["pdf", "jpeg"],
        "maxAgeDays": 90
      }
    }
  ]
}
JSON

此範例限制了可接受的文件類型、格式與有效期限。所有支援的文件限制請參閱建立沙箱任務。

將 data.id 儲存為 TASK_ID、data.revision 儲存為 TASK_REVISION,並將目前的 data.requirements[0].id 儲存為 REQUIREMENT_ID。呼叫 POST /v3/customers/{customerId}/tasks/{taskId}/submissions 時,請讓答覆與所建立的項目類型一致:

說明答覆
文件答覆

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/tasks/${TASK_ID}/submissions" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: sandbox-task-submission-001" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
  "taskRevision": ${TASK_REVISION},
  "answers": [
    {
      "requirementId": "${REQUIREMENT_ID}",
      "answer": {
        "type": "text",
        "value": "Sandbox requirement completed."
      }
    }
  ]
}
JSON

使用 POST /v3/customers/{customerId}/documents 上傳符合要求的檔案,將回傳的 data.id 儲存為 DOCUMENT_ID,然後以文件答覆提交:

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/tasks/${TASK_ID}/submissions" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: sandbox-task-document-submission-001" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{
  "taskRevision": ${TASK_REVISION},
  "answers": [
    {
      "requirementId": "${REQUIREMENT_ID}",
      "answer": {
        "type": "document",
        "documentIds": ["${DOCUMENT_ID}"]
      }
    }
  ]
}
JSON

然後使用 POST /v3/sandbox/tasks/{taskId}/review 接受或拒絕當前的提交:

curl --request POST \
  "${API_BASE}/v3/sandbox/tasks/${TASK_ID}/review" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{"outcome":"accepted"}'

正式環境的任務完成模式請參閱能力與任務。

為沙箱錢包儲值

使用 POST /v3/sandbox/accounts/{accountId}/topup 為發行的錢包儲值:

curl --request POST \
  "${API_BASE}/v3/sandbox/accounts/${ACCOUNT_ID}/topup" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{"amount":"250.00","currency":"USDC"}'

當您想檢視模擬的儲值轉帳時,將回傳的 data.id 儲存為 TRANSFER_ID。儲值 id 即為轉帳 id。透過 GET /v3/transfers/{transferId} 取得單筆,或透過 GET /v3/transfers 列出,即可用沙箱儲值來驗證您的入金處理程式碼路徑。此轉帳投影為已完成的入金穩定幣存款,origin: "inbound_deposit"、method: "stablecoin_transfers"、direction: "stablecoin_move",並會由對應的 accountId、origin、method 與 direction 清單篩選器回傳。

完成或失敗轉帳

使用 POST /v3/sandbox/transfers/{transferId}/state 設定結果:

完成
失敗

curl --request POST \
  "${API_BASE}/v3/sandbox/transfers/${TRANSFER_ID}/state" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{"state":"completed"}'

curl --request POST \
  "${API_BASE}/v3/sandbox/transfers/${TRANSFER_ID}/state" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "state": "failed",
  "stateDetail": {
    "code": "sandbox_review",
    "message": "Sandbox transfer failed."
  }
}
JSON

接下來,請在沙箱中執行入金、出金或發行銀行帳戶流程。

開始使用

客戶引導

建立金流

上線

測試能力就緒

測試待辦任務

為沙箱錢包儲值

完成或失敗轉帳

​測試能力就緒

​測試待辦任務

​為沙箱錢包儲值

​完成或失敗轉帳

測試能力就緒

測試待辦任務

為沙箱錢包儲值

完成或失敗轉帳