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.

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

Test capability readiness

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

Refetch the capability after using the helper. Treat its current status and openTaskIds as the result your product must handle.

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:

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.

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:

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:

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

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:

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