Prima di iniziare
Hai bisogno di un ID cliente, una capability bancaria ready per il metodo e la valuta desiderati e un wallet emesso ready di proprietà dello stesso cliente. ConallowPending, puoi salvare la richiesta mentre la banca selezionata sta ancora esaminando il cliente. Completa il lavoro aperto tramite Capability e task.
1. Crea o seleziona il wallet di regolamento
Crea un wallet emesso tramite Conti e wallet, poi rileggilo. Prosegui solo quando il suo stato corrente consente il regolamento. Salva il suodata.id derivato dalla risposta come SETTLEMENT_WALLET_ID. Non usare un wallet esterno per settlement.accountId.
2. Crea il conto bancario emesso
UsaPOST /v3/customers/{customerId}/accounts con questi header:
Request headers
Request body
data.id restituito come BANK_ACCOUNT_ID. Conserva anche data.status, data.openTaskIds, data.details e la relazione di settlement.
Campi di richiesta opzionali:
Scegli la banca
Inviainstitution quando il cliente ha bisogno di coordinate bancarie di una banca specifica. Swipelux riserva un conto emesso per ogni combinazione di cliente, metodo, valuta e institution. Una richiesta senza institution restituisce 409 conflict se il cliente ha già un conto emesso per quel metodo e quella valuta presso qualsiasi banca. Una richiesta con institution restituisce 409 conflict solo se esiste già un conto per quella banca.
Le letture del conto restituiscono la banca selezionata come institution con id, name e bic. bic può essere null.
L’idempotenza si applica alla banca selezionata. Ripetere la stessa richiesta restituisce il conto originale. Cambiare institution con lo stesso Idempotency-Key restituisce 409 idempotency_conflict.
Salva la richiesta prima dell’approvazione della banca
Per impostazione predefinita, Swipelux accetta una richiesta di conto bancario emesso solo dopo che la capability bancaria è ready. Per raccogliere prima la configurazione del conto del cliente, inviaallowPending: true insieme a institution:
Request body with allowPending
status: "in_review" con statusReason.code impostato su waiting_for_approval. La risposta include anche applicationId e gli openTaskIds della domanda. Completa questi task tramite Capability e task.
La richiesta salvata mantiene l’ID del conto, il wallet di settlement e lo slot del conto. Quando la domanda e la capability sono ready, Swipelux esegue il provisioning delle coordinate bancarie sotto lo stesso BANK_ACCOUNT_ID. Continua a leggere quell’ID. Non creare un’altra richiesta.
Mentre la richiesta salvata è in attesa, occupa lo slot del conto. Un’altra richiesta allowPending per lo stesso slot con un Idempotency-Key diverso restituisce 409 conflict. Il campo holder.accountId del problema indica il conto in attesa. Leggi quel conto invece di riprovare.
Se la domanda viene prima rifiutata, annullata o archiviata, il conto diventa rejected. Non occupa più lo slot del conto.
Scegli la valuta di settlement
Per impostazione predefinita, i depositi vengono regolati nella valuta del wallet di settlement. Impostasettlement.currency su USDC o USDT per scegliere l’asset accreditato indipendentemente dalla valuta del wallet:
Request body with settlement currency
USDT richiede un conto USD e un wallet di settlement su un network che supporta l’accredito di USDT. In caso contrario, la richiesta restituisce 400 invalid_settlement_target. Le letture del conto restituiscono la scelta salvata, anche mentre il conto è in provisioning.
L’ID del conto bancario e l’ID del wallet hanno ruoli diversi. Leggi il provisioning e i dettagli bancari tramite l’ID del conto bancario. Usa l’ID del wallet di settlement per identificare dove vengono accreditati i depositi.
3. Monitora il provisioning
LeggiGET /v3/customers/{customerId}/accounts/{accountId} dopo la creazione e dopo ogni webhook rilevante.
Mantieni l’interfaccia cliente in stato pending finché details è assente. Se openTaskIds non è vuoto, completa gli ultimi task e rileggi il conto. Non dedurre la readiness dal tempo trascorso.
Se il conto è stato salvato con allowPending: true, resta in_review con statusReason.code impostato su waiting_for_approval finché la banca non approva la domanda.
Se l’ultimo statusReason.code è awaiting_assignment, crea il primo pay-in per lo stesso cliente, capability e wallet di settlement tramite Ricevi fondi, poi rileggi il conto bancario. Segui questo ramo solo quando il conto corrente lo richiede.
4. Presenta i dettagli bancari in sicurezza
Mostra solo i dettagli completi restituiti dall’ultima lettura del conto. Quandodetails.referenceRequired è true, mostra l’esatto details.reference e rendilo copiabile. Quando è false, non inventare un reference.
Per i conti swift emessi, mostra details.bankName, details.swiftCode (il BIC della banca ricevente), details.accountNumber, details.accountHolderName e details.accountHolderAddress quando vengono restituiti. Chi invia i fondi deve copiare esattamente l’indirizzo del beneficiario nel bonifico internazionale. Mostra anche details.bankAddress e gli eventuali campi della banca intermediaria restituiti dal conto.
Questi dettagli bancari sono riutilizzabili. Non sostituirli con coordinate di finanziamento di un pay-in con quote, che appartengono solo a quel transfer.
Successivamente, aggiungi i Webhook in modo che gli aggiornamenti di provisioning raggiungano la tua applicazione senza tenere il cliente su una schermata di polling.