Abans de començar
Necessites un ID de client, una capacitat bancària preparada per al mètode i moneda previstos, i una cartera emesa preparada propietat del mateix client. AmballowPending, pots desar la sol·licitud mentre el banc seleccionat encara revisa el client. Completa el treball obert mitjançant Capacitats i tasques.
1. Crea o selecciona la cartera de liquidació
Crea una cartera emesa mitjançant Comptes i carteres, i després torna a llegir-la. Continua només quan el seu estat actual permeti la liquidació. Emmagatzema el seudata.id derivat de la resposta com a SETTLEMENT_WALLET_ID. No utilitzis una cartera externa per a settlement.accountId.
2. Crea el compte bancari emès
UtilitzaPOST /v3/customers/{customerId}/accounts amb aquestes capçaleres:
Request headers
Request body
data.id retornat com a BANK_ACCOUNT_ID. Conserva també data.status, data.openTaskIds, data.details i la relació de liquidació.
Camps opcionals de la sol·licitud:
Escull el banc
Enviainstitution quan el client necessiti dades bancàries d’un banc concret. Swipelux reserva un compte emès per client, mètode, moneda i institució. Una sol·licitud sense institution retorna 409 conflict si el client ja té un compte emès per a aquest mètode i moneda en qualsevol banc. Una sol·licitud amb institution retorna 409 conflict només si ja existeix un compte per a aquest banc.
Les lectures del compte retornen el banc seleccionat com a institution amb id, name i bic. bic pot ser null.
La idempotència s’aplica al banc seleccionat. Repetir la mateixa sol·licitud retorna el compte original. Canviar institution amb la mateixa Idempotency-Key retorna 409 idempotency_conflict.
Desa la sol·licitud abans de l’aprovació del banc
Per defecte, Swipelux accepta una sol·licitud de compte bancari emès només quan la capacitat bancària està preparada. Per recollir abans la configuració del compte del client, enviaallowPending: true amb institution:
Request body with allowPending
status: "in_review" amb statusReason.code establert a waiting_for_approval. La resposta també inclou applicationId i els openTaskIds de la sol·licitud d’alta. Completa aquestes tasques mitjançant Capacitats i tasques.
La sol·licitud desada conserva el seu ID de compte, la cartera de liquidació i la plaça de compte. Quan la sol·licitud d’alta i la capacitat estan preparades, Swipelux provisiona les dades bancàries sota el mateix BANK_ACCOUNT_ID. Continua llegint aquest ID. No creïs una altra sol·licitud.
Mentre la sol·licitud desada espera, ocupa la plaça de compte. Una altra sol·licitud allowPending per a la mateixa plaça amb un Idempotency-Key diferent retorna 409 conflict. El camp holder.accountId del problema indica el compte en espera. Llegeix aquest compte en lloc de tornar-ho a provar.
Si la sol·licitud d’alta es rebutja, es cancel·la o s’arxiva abans, el compte passa a rejected. Ja no ocupa la plaça de compte.
Escull la moneda de liquidació
Per defecte, els dipòsits es liquiden en la moneda de la cartera de liquidació. Estableixsettlement.currency a USDC o USDT per triar l’actiu lliurat independentment de la moneda de la cartera:
Request body with settlement currency
USDT requereix un compte USD i una cartera de liquidació en una xarxa que admeti el lliurament d’USDT. En cas contrari, la sol·licitud retorna 400 invalid_settlement_target. Les lectures del compte retornen l’elecció desada, fins i tot mentre el compte s’està provisionant.
L’ID del compte bancari i l’ID de la cartera tenen rols diferents. Llegeix el provisionament i les dades bancàries a través de l’ID del compte bancari. Utilitza l’ID de la cartera de liquidació per identificar on s’acrediten els dipòsits.
3. Monitoritza el provisionament
LlegeixGET /v3/customers/{customerId}/accounts/{accountId} després de la creació i després de cada webhook rellevant.
Manté la interfície del client pendent mentre details estigui absent. Si openTaskIds no està buit, completa les tasques més recents i torna a obtenir el compte. No infereixis la preparació a partir del temps transcorregut.
Si el compte es va desar amb allowPending: true, es manté a in_review amb statusReason.code establert a waiting_for_approval fins que el banc aprovi la sol·licitud d’alta.
Si l’últim statusReason.code és awaiting_assignment, crea el primer cobrament per al mateix client, capacitat i cartera de liquidació mitjançant Rebre fons, i després torna a llegir el compte bancari. Segueix aquesta branca només quan el compte actual ho sol·liciti.
4. Presenta les dades bancàries de manera segura
Mostra només les dades completes retornades per l’última lectura del compte. Quandetails.referenceRequired és true, mostra la details.reference exacta i fes-la copiable. Quan és false, no inventis una referència.
Per als comptes swift emesos, mostra details.bankName, details.swiftCode (el BIC del banc receptor), details.accountNumber, details.accountHolderName i details.accountHolderAddress quan es retornin. Els remitents han de copiar l’adreça del beneficiari exactament a la transferència internacional. Mostra també details.bankAddress i qualsevol camp de banc intermediari que retorni el compte.
Aquestes dades bancàries són reutilitzables. No les substitueixis per coordenades de finançament d’un cobrament cotitzat, que pertanyen només a aquesta transferència.
A continuació, afegeix Webhooks perquè les actualitzacions de provisionament arribin a la teva aplicació sense mantenir el client en una pantalla de sondeig.