Avant de commencer
Vous avez besoin d’un ID de client, d’une capacité bancaire prête pour la méthode et la devise prévues, et d’un portefeuille émis prêt détenu par le même client. AvecallowPending, vous pouvez enregistrer la demande pendant que la banque sélectionnée examine encore le client. Complétez le travail ouvert via Capacités et tâches.
1. Créer ou sélectionner le portefeuille de règlement
Créez un portefeuille émis via Comptes et portefeuilles, puis lisez-le à nouveau. Continuez uniquement lorsque son statut actuel autorise le règlement. Stockez sondata.id dérivé de la réponse en tant que SETTLEMENT_WALLET_ID. N’utilisez pas de portefeuille externe pour settlement.accountId.
2. Créer le compte bancaire émis
UtilisezPOST /v3/customers/{customerId}/accounts avec ces en-têtes :
Request headers
Request body
data.id renvoyé en tant que BANK_ACCOUNT_ID. Conservez également data.status, data.openTaskIds, data.details et la relation de règlement.
Champs de requête facultatifs :
Choisir la banque
Envoyezinstitution lorsque le client a besoin de coordonnées bancaires d’une banque précise. Swipelux réserve un compte émis par client, méthode, devise et institution. Une requête sans institution renvoie 409 conflict si le client possède déjà un compte émis pour cette méthode et cette devise auprès de n’importe quelle banque. Une requête avec institution renvoie 409 conflict uniquement si un compte existe déjà pour cette banque.
Les lectures de compte renvoient la banque sélectionnée sous institution avec id, name et bic. bic peut valoir null.
L’idempotence s’applique à la banque sélectionnée. Rejouer la même requête renvoie le compte d’origine. Modifier institution avec la même Idempotency-Key renvoie 409 idempotency_conflict.
Enregistrer la demande avant l’approbation de la banque
Par défaut, Swipelux accepte une demande de compte bancaire émis uniquement lorsque la capacité bancaire est prête. Pour recueillir plus tôt la configuration du compte du client, envoyezallowPending: true avec institution :
Request body with allowPending
status: "in_review" avec statusReason.code défini sur waiting_for_approval. La réponse inclut également applicationId et les openTaskIds du dossier. Complétez ces tâches via Capacités et tâches.
La demande enregistrée conserve son ID de compte, son portefeuille de règlement et son emplacement de compte. Une fois le dossier et la capacité prêts, Swipelux provisionne les coordonnées bancaires sous le même BANK_ACCOUNT_ID. Continuez à lire cet ID. Ne créez pas d’autre demande.
Tant que la demande enregistrée est en attente, elle réserve l’emplacement de compte. Une autre demande allowPending pour le même emplacement avec un Idempotency-Key différent renvoie 409 conflict. Le champ holder.accountId du problème indique le compte en attente. Lisez ce compte au lieu de réessayer.
Si le dossier est d’abord rejeté, annulé ou archivé, le compte passe à rejected. Il ne réserve plus l’emplacement de compte.
Choisir la devise de règlement
Par défaut, les dépôts sont réglés dans la devise du portefeuille de règlement. Définissezsettlement.currency sur USDC ou USDT pour choisir l’actif livré indépendamment de la devise du portefeuille :
Request body with settlement currency
USDT nécessite un compte USD et un portefeuille de règlement sur un réseau qui prend en charge la livraison d’USDT. Sinon, la requête renvoie 400 invalid_settlement_target. Les lectures de compte renvoient le choix enregistré, y compris pendant le provisionnement du compte.
L’ID du compte bancaire et l’ID du portefeuille ont des rôles différents. Lisez le provisionnement et les coordonnées bancaires via l’ID du compte bancaire. Utilisez l’ID du portefeuille de règlement pour identifier où les dépôts sont crédités.
3. Surveiller le provisionnement
LisezGET /v3/customers/{customerId}/accounts/{accountId} après la création et après chaque webhook pertinent.
Maintenez l’interface client en attente tant que details est absent. Si openTaskIds n’est pas vide, complétez les dernières tâches et récupérez à nouveau le compte. N’inférez pas la disponibilité à partir du temps écoulé.
Si le compte a été enregistré avec allowPending: true, il reste in_review avec statusReason.code défini sur waiting_for_approval jusqu’à ce que la banque approuve le dossier.
Si le dernier statusReason.code est awaiting_assignment, créez le premier encaissement pour le même client, la même capacité et le même portefeuille de règlement via Recevoir des fonds, puis lisez à nouveau le compte bancaire. Suivez cette branche uniquement lorsque le compte actuel le demande.
4. Présenter les coordonnées bancaires en toute sécurité
Affichez uniquement les coordonnées complètes renvoyées par la dernière lecture du compte. Lorsquedetails.referenceRequired est true, affichez exactement la details.reference et rendez-la copiable. Lorsqu’elle est false, n’inventez pas de référence.
Pour les comptes swift émis, affichez details.bankName, details.swiftCode (le BIC de la banque réceptrice), details.accountNumber, details.accountHolderName et details.accountHolderAddress lorsqu’ils sont renvoyés. Les émetteurs doivent copier exactement l’adresse du bénéficiaire dans le virement international. Affichez également details.bankAddress et tous les champs de banque intermédiaire renvoyés par le compte.
Ces coordonnées bancaires sont réutilisables. Ne les remplacez pas par des coordonnées de financement provenant d’un encaissement avec devis, qui n’appartiennent qu’à ce transfert.
Ensuite, ajoutez des Webhooks afin que les mises à jour de provisionnement atteignent votre application sans garder le client sur un écran de polling.