Pruebas en sandbox

El sandbox utiliza el mismo host de la API que producción. Una clave de API de sandbox selecciona el entorno de pruebas, donde los helpers simulan resultados sin mover fondos reales. Mantén la clave en tu backend. Los helpers de sandbox no sustituyen al cumplimiento normativo ni al onboarding de producción. Utiliza Errores y reintentos para probar cómo gestiona tu integración los fallos de validación, de estado y de plataforma reintenables devueltos por las operaciones del sandbox.

Environment variables

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

Prueba la disponibilidad de una capacidad

En el sandbox, las capacidades ACH, Wire y SWIFT, tanto con nombre como agrupadas, solo se ofrecen en JPMorgan Chase (jpmorgan). Omite institutions al solicitar una de estas capacidades y Swipelux selecciona jpmorgan. Indicar cualquier otro banco devuelve 422 capability_institutions_unsupported. La lista de capacidades admitidas en el sandbox solo muestra jpmorgan para estos métodos. El enrutamiento de producción y otros métodos, como RTP, Pix y SPEI, no cambian.

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

Después de solicitar una capacidad, establece su estado de sandbox con 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"}'

Vuelve a consultar la capacidad después de usar el helper. Considera su status y openTaskIds actuales como el resultado que tu producto debe gestionar. Una respuesta 200 aún puede mostrar trabajo pendiente, como tareas del cliente o una revisión pending. El helper devuelve 409 capability_status_blocked cuando la capacidad no puede alcanzar el estado solicitado por un motivo que no puedes resolver en el sandbox, como approval_scope_review_required, una retención operativa o un estado terminal. El statusReason del problema incluye el código y el mensaje del motivo de la capacidad, con retryable: false. Lee la capacidad para obtener la resolution del motivo. Forzar una capacidad con nombre a rejected por segunda vez devuelve la misma capacidad sin cambios. Forzar una capacidad rechazada a restricted o ready devuelve 422 invalid_capability. En su lugar, crea un cliente de sandbox nuevo para probar esos estados.

Prueba una tarea abierta

Crea una tarea de sandbox con POST /v3/sandbox/tasks. Asígnala al recurso cuyo flujo de trabajo estés probando y usa items para describir lo que el cliente debe enviar. Esta guía muestra flujos de capacidad y transferencia; la Referencia de la API define el ámbito de cliente y el esquema completo de la solicitud. Usa un elemento explanation para una respuesta de texto y un elemento document para una carga. Los nuevos elementos profile también requieren profilePointer, un puntero JSON que identifica el campo del cliente. Consulta Crear tarea de sandbox para ver los demás tipos de elementos y campos. Para el ejemplo de transferencia, crea primero una transferencia de sandbox mediante un flujo de entrada de fondos o pago y luego exporta el data.id devuelto:

Transfer ID

export TRANSFER_ID='tr_replace_with_your_transfer_id'

Capacidad + explicación
RFI de transferencia + documento

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

Aplica el ámbito de la tarea a la transferencia bajo revisión y solicita un documento con constraints que acoten los tipos, formatos y antigüedad aceptados.

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

El ejemplo limita el tipo, el formato y la antigüedad aceptados del documento. Consulta Crear tarea de sandbox para ver todas las restricciones de documento compatibles.

Guarda data.id como TASK_ID, data.revision como TASK_REVISION y el data.requirements[0].id actual como REQUIREMENT_ID. Al llamar a POST /v3/customers/{customerId}/tasks/{taskId}/submissions, haz que la respuesta coincida con el elemento que creaste:

Respuesta de explicación
Respuesta de documento

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

Sube un archivo que cumpla los requisitos con POST /v3/customers/{customerId}/documents, guarda el data.id devuelto como DOCUMENT_ID y envíalo como respuesta de documento:

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

Luego acepta o rechaza el envío actual con 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"}'

Puedes revisar las tareas creadas con POST /v3/sandbox/tasks y las tareas de admisión de capacidades que Swipelux recopila. Revisar una tarea que pertenece a Operaciones o a otro flujo de trabajo devuelve 409 task_not_sandbox_reviewable. Esa tarea sigue siendo legible a través de los endpoints de tareas y espera a que su propietario la revise. 404 task_not_found significa que el ID de la tarea es desconocido o pertenece a otro comercio. Utiliza Capacidades y tareas para el patrón de finalización de tareas en producción.

Financia una cartera de sandbox

Acredita una cartera emitida con 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"}'

Guarda el data.id devuelto como TRANSFER_ID cuando quieras inspeccionar la transferencia de financiación simulada. El id del topup es un id de transferencia. Recupéralo mediante GET /v3/transfers/{transferId} o lístalo mediante GET /v3/transfers para ejercitar tu ruta de código de depósito entrante contra los topups del sandbox. La proyección de la transferencia es un depósito entrante de stablecoin completado con origin: "inbound_deposit", method: "stablecoin_transfers" y direction: "stablecoin_move", y se devuelve con los filtros de listado correspondientes de accountId, origin, method y direction.

Completa o falla una transferencia

Establece el resultado con POST /v3/sandbox/transfers/{transferId}/state:

Completar
Fallar

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

A continuación, ejecuta un flujo de cobro, pago o cuenta bancaria emitida en sandbox.

Comienza

Incorpora clientes

Crea flujos de dinero

Lanzamiento

Pruebas en sandbox

Prueba la disponibilidad de una capacidad

Prueba una tarea abierta

Financia una cartera de sandbox

Completa o falla una transferencia

​Prueba la disponibilidad de una capacidad

​Prueba una tarea abierta

​Financia una cartera de sandbox

​Completa o falla una transferencia

Prueba la disponibilidad de una capacidad

Prueba una tarea abierta

Financia una cartera de sandbox

Completa o falla una transferencia