沙箱測試

沙箱使用與正式環境相同的 API 主機。沙箱 API 金鑰會選擇測試環境,其中的輔助工具可模擬結果而不移動實際資金。請將金鑰保存在後端。沙箱輔助工具不會取代正式環境的法遵或入駐流程。請使用錯誤與重試測試您的整合如何處理沙箱操作回傳的驗證、狀態與可重試的平台失敗。

Environment variables

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

測試能力就緒

在沙盒中,ACH、Wire 與 SWIFT 能力(包括指定銀行與集區式)僅由 JPMorgan Chase(jpmorgan)提供。請求這些能力時若省略 institutions,Swipelux 會選擇 jpmorgan。指定任何其他銀行都會回傳 422 capability_institutions_unsupported。沙盒中的支援能力清單對這些方式僅顯示 jpmorgan。正式環境的路由以及 RTP、Pix 與 SPEI 等其他方式維持不變。

Request a sandbox bank capability

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/capabilities/${CAPABILITY_ID}" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: sandbox-capability-001" \
  --header "Content-Type: application/json" \
  --data '{"institutions":["jpmorgan"]}'

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

Set capability 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 視為您的產品必須處理的結果。 200 回應仍可能顯示未完成的工作,例如客戶任務或 pending 審核。當能力因你無法在沙盒中排除的原因而無法達到所請求的狀態時,輔助工具會回傳 409 capability_status_blocked,例如 approval_scope_review_required、營運凍結或終止狀態。問題回應中的 statusReason 包含該能力的原因代碼與訊息,並帶有 retryable: false。請讀取該能力以取得該原因的 resolution。第二次將指定能力強制設為 rejected 時,會回傳未變更的同一能力。將已拒絕的能力強制設為 restricted 或 ready 會回傳 422 invalid_capability。請改為建立新的沙盒客戶來測試這些狀態。

測試待辦任務

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

Transfer 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 縮小可接受的類型、格式與時效,請求提供文件。

Create document task

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,然後以文件答覆提交:

Upload document

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 接受或拒絕當前的提交:

Review submission

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/tasks 建立的任務,以及 Swipelux 收集的能力受理任務。審核由營運團隊或其他工作流程擁有的任務會回傳 409 task_not_sandbox_reviewable。該任務仍可透過任務端點讀取,並等待其擁有者審核。404 task_not_found 表示該任務 ID 未知或屬於其他商家。正式環境的任務完成模式請參閱能力與任務。

為沙箱錢包儲值

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

Top up issued wallet

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

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

開始使用

客戶引導

建立金流

上線

測試能力就緒

測試待辦任務

為沙箱錢包儲值

完成或失敗轉帳

​測試能力就緒

​測試待辦任務

​為沙箱錢包儲值

​完成或失敗轉帳

測試能力就緒

測試待辦任務

為沙箱錢包儲值

完成或失敗轉帳