Quickstart

1. Configura sandbox

Usa una chiave API sandbox dal tuo backend:

Sandbox setup

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

La chiave seleziona l’ambiente sandbox sullo stesso host API condiviso.

2. Crea un cliente

Crea un cliente individuale con POST /v3/customers:

Create customer

curl --request POST \
  "${API_BASE}/v3/customers" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: quickstart-customer-001" \
  --header "Content-Type: application/json" \
  --data '{"type":"individual","externalId":"quickstart-customer-001"}'

Salva data.id come CUSTOMER_ID.

3. Scegli il risultato

Pay-in: ricevi USD e regola USDC nel wallet emesso del cliente.
Payout: invia USDC dal wallet emesso del cliente a un conto bancario di proprietà del cliente.
Conto bancario emesso: emetti un conto ACH/USD che si regola nel wallet emesso del cliente.

Per un payout verso terze parti, segui Recipients o Invia fondi.

4. Trova una capability idonea

Elenca le capability supportate con GET /v3/customers/{customerId}/capabilities/supported:

Supported capabilities

curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/capabilities/supported" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}"

Scegli una voce della risposta con availability impostato su available o beta, eligibility.eligible impostato su true, con le directions e il method necessari e l’accountType corrispondente. Usa il wallet emesso del cliente come destinazione del pay-in, sorgente del payout o conto di regolamento del conto bancario; usa il conto di proprietà del cliente come destinationId per questo percorso di payout. Se vengono restituite institutions, usa solo una scelta di institution restituita. Salva l’id della voce come CAPABILITY_ID; non codificare in modo rigido un ID di capability universale.

5. Richiedi la capability

Richiedi la capability selezionata con POST /v3/customers/{customerId}/capabilities/{capabilityId}:

Request capability

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/capabilities/${CAPABILITY_ID}" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: quickstart-capability-001" \
  --header "Content-Type: application/json" \
  --data '{}'

Salva data.status come CAPABILITY_STATUS e data.openTaskIds come TASK_IDS.

6. Completa l’onboarding in sandbox

Se TASK_IDS non è vuoto, completa ogni requisito corrente tramite Capability e task. Per questa guida, imposta la capability su ready con POST /v3/sandbox/customers/{customerId}/capabilities/{capabilityId}/status:

Set capability ready

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

Questo controllo di test non è l’onboarding di produzione. Rileggi con GET /v3/customers/{customerId}/capabilities/{capabilityId}:

Refetch capability

curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/capabilities/${CAPABILITY_ID}" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}"

Aggiorna CAPABILITY_STATUS e TASK_IDS da data.status e data.openTaskIds. Prosegui solo quando CAPABILITY_STATUS è ready.

7. Costruisci il flusso selezionato

Crea un wallet USDC emesso su Base con POST /v3/customers/{customerId}/accounts:

Create wallet

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/accounts" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: quickstart-flow-wallet-001" \
  --header "Content-Type: application/json" \
  --data '{"origin":"issued","type":"wallet","currency":"USDC","network":"base"}'

Salva data.id come FLOW_WALLET_ID, data.status come FLOW_WALLET_STATUS e data.openTaskIds come FLOW_WALLET_TASK_IDS. Se FLOW_WALLET_TASK_IDS non è vuoto, completa i task correnti tramite Capability e task. Rileggi il wallet con GET /v3/customers/{customerId}/accounts/{accountId}:

Refetch wallet

curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/accounts/${FLOW_WALLET_ID}" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}"

Aggiorna FLOW_WALLET_STATUS e FLOW_WALLET_TASK_IDS da data.status e data.openTaskIds. Prosegui solo quando FLOW_WALLET_STATUS è ready.

Pay-in
Payout
Conto bancario emesso

Crea un quote USD-a-USDC con POST /v3/quotes:

Pay-in quote

curl --request POST \
  "${API_BASE}/v3/quotes" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: quickstart-payin-quote-001" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{"customerId":"${CUSTOMER_ID}","capabilityId":"${CAPABILITY_ID}","in":{"amount":"150.00","currency":"USD"},"destinationId":"${FLOW_WALLET_ID}","out":{"currency":"USDC"}}
JSON

Salva data.id come QUOTE_ID, quindi eseguilo con POST /v3/transfers:

Execute quote

curl --request POST \
  "${API_BASE}/v3/transfers" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: quickstart-payin-transfer-001" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{"quoteId":"${QUOTE_ID}"}
JSON

Salva data.id come TRANSFER_ID. Recupera le istruzioni con GET /v3/transfers/{transferId}/instructions:

Funding instructions

curl --request GET \
  "${API_BASE}/v3/transfers/${TRANSFER_ID}/instructions" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}"

La risposta contiene data.transferId e data.instructions. Salva data.transferId come TRANSFER_ID e data.instructions come FUNDING_INSTRUCTIONS.

Finanzia il wallet ready con POST /v3/sandbox/accounts/{accountId}/topup:

Fund wallet

curl --request POST \
  "${API_BASE}/v3/sandbox/accounts/${FLOW_WALLET_ID}/topup" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{"amount":"250.00","currency":"USDC"}'

Crea un conto ACH di proprietà del cliente con POST /v3/customers/{customerId}/accounts:

Create ACH account

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/accounts" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: quickstart-payout-account-001" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{"origin":"external","type":"bank","methods":["ach"],"country":"US","currency":"USD","details":{"routingNumber":"021000021","accountNumber":"123456789","accountType":"checking","bankName":"Example Bank","accountHolderName":"Amina Diallo"}}
JSON

Salva data.id come PAYOUT_ACCOUNT_ID, data.status come PAYOUT_ACCOUNT_STATUS e data.openTaskIds come PAYOUT_ACCOUNT_TASK_IDS. Se PAYOUT_ACCOUNT_TASK_IDS non è vuoto, completa i task correnti tramite Capability e task.Rileggilo con GET /v3/customers/{customerId}/accounts/{accountId}:

Refetch ACH account

curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/accounts/${PAYOUT_ACCOUNT_ID}" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}"

Aggiorna PAYOUT_ACCOUNT_STATUS e PAYOUT_ACCOUNT_TASK_IDS da data.status e data.openTaskIds. Prosegui solo quando PAYOUT_ACCOUNT_STATUS è ready, quindi crea il quote con POST /v3/quotes:

Payout quote

curl --request POST \
  "${API_BASE}/v3/quotes" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: quickstart-payout-quote-001" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{"customerId":"${CUSTOMER_ID}","capabilityId":"${CAPABILITY_ID}","in":{"amount":"150.00","currency":"USDC","accountId":"${FLOW_WALLET_ID}"},"destinationId":"${PAYOUT_ACCOUNT_ID}","out":{"currency":"USD"}}
JSON

Salva data.id come QUOTE_ID, eseguilo con POST /v3/transfers e salva il data.id restituito come TRANSFER_ID:

Execute payout

curl --request POST \
  "${API_BASE}/v3/transfers" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: quickstart-payout-transfer-001" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{"quoteId":"${QUOTE_ID}"}
JSON

Crea un conto ACH/USD regolato sul wallet ready con POST /v3/customers/{customerId}/accounts:

Issue bank account

curl --request POST \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/accounts" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}" \
  --header "Idempotency-Key: quickstart-bank-account-001" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{"origin":"issued","type":"bank","method":"ach","country":"US","currency":"USD","settlement":{"accountId":"${FLOW_WALLET_ID}"}}
JSON

Salva data.id come BANK_ACCOUNT_ID, poi leggi il provisioning con GET /v3/customers/{customerId}/accounts/{accountId}:

Check provisioning

curl --request GET \
  "${API_BASE}/v3/customers/${CUSTOMER_ID}/accounts/${BANK_ACCOUNT_ID}" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}"

Salva data.status come BANK_ACCOUNT_STATUS, data.details come BANK_ACCOUNT_DETAILS e data.openTaskIds come BANK_ACCOUNT_TASK_IDS. Completa eventuali task correnti, poi rileggi il conto finché il suo stato non ne consente l’uso e data.details è presente.I dettagli bancari potrebbero non essere presenti immediatamente. Il ramo è completo quando puoi presentare le esatte coordinate bancarie riutilizzabili restituite in BANK_ACCOUNT_DETAILS. Non costruire né mostrare mai coordinate segnaposto mentre il conto è ancora in provisioning.

Per pay-in e payout, monitora TRANSFER_ID con GET /v3/transfers/{transferId}:

Monitor transfer

curl --request GET \
  "${API_BASE}/v3/transfers/${TRANSFER_ID}" \
  --header "X-API-Key: ${SWIPELUX_SANDBOX_API_KEY}"

Pay-in

Costruisci il flusso completo di pay-in.

Payout

Costruisci la gestione del payout di produzione.

Conto bancario emesso

Gestisci provisioning e dettagli.

Successivamente, aggiungi i webhook. Ogni richiesta sopra include già un link al proprio schema completo nell’API Reference e alla pagina di stato.

Inizia

Onboarding dei clienti

Costruisci i flussi di denaro

Lancio

1. Configura sandbox

2. Crea un cliente

3. Scegli il risultato

4. Trova una capability idonea

5. Richiedi la capability

6. Completa l’onboarding in sandbox

7. Costruisci il flusso selezionato

Pay-in

Payout

Conto bancario emesso

​1. Configura sandbox

​2. Crea un cliente

​3. Scegli il risultato

​4. Trova una capability idonea

​5. Richiedi la capability

​6. Completa l’onboarding in sandbox

​7. Costruisci il flusso selezionato

Pay-in

Payout

Conto bancario emesso

1. Configura sandbox

2. Crea un cliente

3. Scegli il risultato

4. Trova una capability idonea

5. Richiedi la capability

6. Completa l’onboarding in sandbox

7. Costruisci il flusso selezionato