Conti e wallet

Ogni conto appartiene a un cliente. Sceglilo usando due dimensioni: chi lo gestisce e se è un wallet o un conto bancario. Le operazioni di elenco, creazione, lettura, aggiornamento e archiviazione degli account cliente sono sotto /v3/customers/{customerId}/accounts; le operazioni su un singolo account aggiungono /{accountId}. Non esiste una ricerca inversa da accountId a customerId. Salva il customerId insieme a ogni accountId per poter indirizzare l’account nelle richieste successive.

Scegli un conto

Conto	Usalo per
Wallet emesso	Detenere un saldo in stablecoin custoditi, finanziare un payout, ricevere un pay-in o regolare un conto bancario emesso.
Conto bancario emesso	Fornire al cliente coordinate bancarie riutilizzabili che si regolano su un wallet emesso.
Wallet esterno	Registrare un indirizzo blockchain di proprietà del cliente.
Conto bancario esterno	Registrare un conto bancario di proprietà del cliente per un payout di prima parte.

issued significa che Swipelux crea e gestisce la risorsa. external registra un endpoint di proprietà del cliente. Un endpoint di terze parti va sotto una recipient e destination, non nella lista dei conti del cliente. Prima di iniziare la procedura First pay-in del pannello commerciante per carte o Apple Pay, crea un wallet Polygon per quel cliente. La procedura offre solo quel wallet Polygon e non può continuare senza di esso. Questo prerequisito si applica alla procedura del pannello commerciante; le integrazioni API dirette devono usare solo valute, reti, metodi e tipi di conto restituiti per il cliente e la capacità correnti.

Crea il conto

Usa POST /v3/customers/{customerId}/accounts. Invia questi header con uno dei body di richiesta seguenti:

Request headers

X-API-Key: ${SWIPELUX_API_KEY}
Idempotency-Key: account-create-001
Content-Type: application/json

Wallet emesso
Conto bancario emesso
Wallet esterno
Conto bancario esterno

{
  "origin": "issued",
  "type": "wallet",
  "currency": "USDC",
  "network": "base",
  "label": "Settlement wallet"
}

{
  "origin": "issued",
  "type": "bank",
  "method": "ach",
  "country": "US",
  "currency": "USD",
  "settlement": {
    "accountId": "${SETTLEMENT_WALLET_ID}"
  },
  "label": "USD account"
}

{
  "origin": "external",
  "type": "wallet",
  "currency": "USDC",
  "network": "polygon",
  "details": {
    "address": "0x4997b0a68bebc1b0d80a93567ba7002be92b8b11"
  },
  "label": "Customer Polygon wallet"
}

{
  "origin": "external",
  "type": "bank",
  "methods": ["ach", "wire"],
  "country": "US",
  "currency": "USD",
  "details": {
    "routingNumber": "021000021",
    "accountNumber": "123456789",
    "accountType": "checking",
    "bankName": "Example Bank",
    "accountHolderName": "Acme Payments SAS"
  },
  "label": "Customer operating account"
}

Swipelux convalida gli identificativi bancari quando invii la richiesta. Gli IBAN devono rispettare il formato specifico del paese e il checksum. I BIC devono essere di 8 o 11 caratteri. I routing number statunitensi devono essere di 9 cifre con un checksum ABA valido. I valori non validi restituiscono 400 validation_error prima che Swipelux registri il conto. Questi controlli confermano solo il formato. Non confermano che il conto bancario esista né chi ne sia il titolare. Usa solo valute, network, metodi e tipi di conto restituiti per il cliente e la capability correnti. Non copiare la disponibilità da un altro cliente o ambiente.

Attendi che il conto sia utilizzabile

Salva data.id, data.status e data.openTaskIds dalla risposta di creazione. Leggi l’ultimo conto con GET /v3/customers/{customerId}/accounts/{accountId} prima di quotare un transfer o mostrare dettagli bancari. Usa il conto solo quando il suo stato corrente consente l’operazione successiva. Se ci sono ID task aperti, completali tramite Capability e task. Un conto bancario emesso può restituire details: null durante il provisioning. Presenta i dettagli bancari solo dopo che una lettura corrente restituisce il set completo. Se details.referenceRequired è true, mostra l’esatto details.reference insieme alle coordinate bancarie.

Mantieni espliciti i ruoli del conto

Per un payout, il wallet emesso è la sorgente in in.accountId. Un conto bancario di proprietà del cliente è il destinationId. Per un conto bancario emesso, settlement.accountId è il wallet emesso che riceve i depositi accoppiati. Successivamente, usa un conto ready in Ricevi fondi, Invia fondi o Emetti un conto bancario.

Inizia

Onboarding dei clienti

Costruisci i flussi di denaro

Lancio

Scegli un conto

Crea il conto

Attendi che il conto sia utilizzabile

Mantieni espliciti i ruoli del conto

​Scegli un conto

​Crea il conto

​Attendi che il conto sia utilizzabile

​Mantieni espliciti i ruoli del conto

Scegli un conto

Crea il conto

Attendi che il conto sia utilizzabile

Mantieni espliciti i ruoli del conto