沙盒测试

沙盒与生产环境使用同一个 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 即为 transfer 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

接下来,在沙盒中运行入金、出金或发行银行账户流程。

开始使用

客户入驻

构建资金流

上线

测试能力的就绪状态

测试一个待办任务

为沙盒钱包充值

完成或失败一笔转账

​测试能力的就绪状态

​测试一个待办任务

​为沙盒钱包充值

​完成或失败一笔转账

测试能力的就绪状态

测试一个待办任务

为沙盒钱包充值

完成或失败一笔转账