Test in sandbox

Sandbox usa lo stesso host API della produzione. Una chiave API sandbox seleziona l’ambiente di test, dove gli helper simulano i risultati senza spostare fondi reali. Mantieni la chiave sul tuo backend. Gli helper sandbox non sostituiscono la compliance o l’onboarding di produzione. Usa Errori e nuovi tentativi per testare come la tua integrazione gestisce i fallimenti di validazione, di stato e i fallimenti di piattaforma ritentabili restituiti dalle operazioni sandbox.

Environment variables

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

Testa la readiness di una capability

Nella sandbox, le capability ACH, Wire e SWIFT, sia nominate sia in pool, sono servite solo presso JPMorgan Chase (jpmorgan). Ometti institutions quando richiedi una di queste capability e Swipelux seleziona jpmorgan. Indicare qualsiasi altra banca restituisce 422 capability_institutions_unsupported. Nella sandbox, l’elenco delle capability supportate mostra solo jpmorgan per questi metodi. Il routing di produzione e gli altri metodi, come RTP, Pix e SPEI, restano invariati.

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

Dopo aver richiesto una capability, imposta il suo stato 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"}'

Rileggi la capability dopo aver usato l’helper. Considera il suo status corrente e gli openTaskIds come il risultato che il tuo prodotto deve gestire. Una risposta 200 può comunque mostrare lavoro aperto, come task del cliente o una revisione pending. L’helper restituisce 409 capability_status_blocked quando la capability non può raggiungere lo stato richiesto per un motivo che non puoi risolvere nella sandbox, come approval_scope_review_required, un blocco operativo o uno stato terminale. Il campo statusReason del problema riporta il codice e il messaggio del motivo della capability, con retryable: false. Leggi la capability per ottenere la resolution del motivo. Forzare una capability nominata a rejected una seconda volta restituisce la stessa capability invariata. Forzare una capability rifiutata a restricted o ready restituisce 422 invalid_capability. Per testare questi stati, crea invece un nuovo cliente sandbox.

Testa un task aperto

Crea un task sandbox con POST /v3/sandbox/tasks. Associalo alla risorsa del workflow che stai testando e usa items per descrivere ciò che il cliente deve inviare. Questa guida mostra i workflow di capability e transfer; l’API Reference definisce lo scope customer e lo schema completo della richiesta. Usa un elemento explanation per una risposta testuale e un elemento document per un caricamento. I nuovi elementi profile richiedono anche profilePointer, un puntatore JSON che identifica il campo del cliente. Consulta Create sandbox task per gli altri tipi di elementi e campi. Per l’esempio di transfer, crea prima un transfer sandbox tramite un flusso di pay-in o payout, quindi esporta il data.id restituito:

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

Assegna al task lo scope del transfer sotto revisione e richiedi un documento con constraints che restringano tipi, formati ed età accettati.

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

L’esempio limita tipo, formato e anzianità accettati del documento. Consulta Create sandbox task per tutti i vincoli di documento supportati.

Salva data.id come TASK_ID, data.revision come TASK_REVISION e l’attuale data.requirements[0].id come REQUIREMENT_ID. Quando chiami POST /v3/customers/{customerId}/tasks/{taskId}/submissions, abbina la risposta all’elemento creato:

Risposta di spiegazione
Risposta 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

Carica un file corrispondente con POST /v3/customers/{customerId}/documents, salva il data.id restituito come DOCUMENT_ID e invialo come risposta 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

Poi accetta o rifiuta la submission corrente 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"}'

Puoi revisionare i task creati da POST /v3/sandbox/tasks e i task di raccolta delle capability che Swipelux acquisisce. La revisione di un task di proprietà di Operations o di un altro workflow restituisce 409 task_not_sandbox_reviewable. Quel task resta leggibile tramite gli endpoint dei task e attende la revisione da parte del suo proprietario. 404 task_not_found indica che l’ID del task è sconosciuto o appartiene a un altro merchant. Usa Capability e task per il pattern di completamento dei task in produzione.

Finanzia un wallet sandbox

Accredita un wallet emesso 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"}'

Salva il data.id restituito come TRANSFER_ID quando vuoi ispezionare il transfer di finanziamento simulato. L’id del topup è un id di transfer. Recuperalo tramite GET /v3/transfers/{transferId} o elencalo tramite GET /v3/transfers per esercitare il tuo code path di deposito in entrata sui topup in sandbox. La proiezione del transfer è un deposito stablecoin in entrata completato con origin: "inbound_deposit", method: "stablecoin_transfers" e direction: "stablecoin_move", ed è restituita dai corrispondenti filtri di elenco accountId, origin, method e direction.

Completa o fai fallire un transfer

Imposta il risultato con POST /v3/sandbox/transfers/{transferId}/state:

Completa
Fallisci

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

Successivamente, esegui un flusso di pay-in, payout o conto bancario emesso in sandbox.

Inizia

Onboarding dei clienti

Costruisci i flussi di denaro

Lancio

Testa la readiness di una capability

Testa un task aperto

Finanzia un wallet sandbox

Completa o fai fallire un transfer

​Testa la readiness di una capability

​Testa un task aperto

​Finanzia un wallet sandbox

​Completa o fai fallire un transfer

Testa la readiness di una capability

Testa un task aperto

Finanzia un wallet sandbox

Completa o fai fallire un transfer