Sandbox testing

Sandbox uses the same API host as production. A sandbox API key selects the test environment, where helpers simulate outcomes without moving real funds. Keep the key on your backend. Sandbox helpers do not replace production compliance or onboarding. Use Errors and retries to test how your integration handles validation, state, and retryable platform failures returned by sandbox operations.

Environment variables

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

Test capability readiness

In sandbox, ACH, Wire, and SWIFT capabilities, both named and pooled, are served only at JPMorgan Chase (jpmorgan). Omit institutions when you request one of these capabilities and Swipelux selects jpmorgan. Naming any other bank returns 422 capability_institutions_unsupported. The supported-capabilities list in sandbox shows only jpmorgan for these methods. Production routing and other methods, such as RTP, Pix, and SPEI, are unchanged.

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"]}'

After requesting a capability, set its sandbox status with 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"}'

Refetch the capability after using the helper. Treat its current status and openTaskIds as the result your product must handle. A 200 response can still show open work, such as customer tasks or a pending review. The helper returns 409 capability_status_blocked when the capability cannot reach the requested status for a reason you can’t clear in sandbox, such as approval_scope_review_required, an operational hold, or a terminal status. The problem’s statusReason carries the capability’s reason code and message, with retryable: false. Read the capability for the reason’s resolution. Forcing a named capability to rejected a second time returns the same capability unchanged. Forcing a rejected capability to restricted or ready returns 422 invalid_capability. Create a fresh sandbox customer to test those statuses instead.

Test an open task

Create a sandbox task with POST /v3/sandbox/tasks. Scope it to the resource whose workflow you are testing and use items to describe what the customer must submit. This guide shows capability and transfer workflows; API Reference defines the customer scope and the complete request schema. Use an explanation item for a text response and a document item for an upload. New profile items also require profilePointer, a JSON Pointer naming the customer field. See Create sandbox task for the other item types and fields. For the transfer example, first create a sandbox transfer through a pay-in or payout flow, then export its returned data.id:

Transfer ID

export TRANSFER_ID='tr_replace_with_your_transfer_id'

Capability + explanation
Transfer RFI + document

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

Scope the task to the transfer under review and request a document with constraints that narrow accepted types, formats, and age.

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

The example narrows the accepted document type, format, and age. See Create sandbox task for every supported document constraint.

Store data.id as TASK_ID, data.revision as TASK_REVISION, and the current data.requirements[0].id as REQUIREMENT_ID. Match the answer to the item you created when you call POST /v3/customers/{customerId}/tasks/{taskId}/submissions:

Explanation answer
Document answer

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

Upload a matching file with POST /v3/customers/{customerId}/documents, then store the returned data.id as DOCUMENT_ID and submit it as a document answer:

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

Then accept or reject the current submission with 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"}'

You can review tasks created by POST /v3/sandbox/tasks and the capability intake tasks that Swipelux collects. Reviewing a task that Operations or another workflow owns returns 409 task_not_sandbox_reviewable. That task stays readable through the task endpoints and waits for its owner to review it. 404 task_not_found means the task ID is unknown or belongs to another merchant. Use Capabilities and tasks for the production task-completion pattern.

Fund a sandbox wallet

Credit an issued wallet with 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"}'

Store the returned data.id as TRANSFER_ID when you want to inspect the simulated funding transfer. The topup id is a transfer id. Fetch it through GET /v3/transfers/{transferId} or list it through GET /v3/transfers to exercise your inbound-deposit code path against sandbox topups. The transfer projection is a completed inbound stablecoin deposit with origin: "inbound_deposit", method: "stablecoin_transfers", and direction: "stablecoin_move", and it is returned by the matching accountId, origin, method, and direction list filters.

Complete or fail a transfer

Set the outcome with POST /v3/sandbox/transfers/{transferId}/state:

Complete
Fail

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

Next, run a pay-in, payout, or issued bank account flow in sandbox.

Get started

Onboard customers

Build money flows

Launch

Test capability readiness

Test an open task

Fund a sandbox wallet

Complete or fail a transfer

​Test capability readiness

​Test an open task

​Fund a sandbox wallet

​Complete or fail a transfer

Test capability readiness

Test an open task

Fund a sandbox wallet

Complete or fail a transfer