Soldes et cartes

IBAN pour vos clients

Ouvrir un compte bancaire européen au nom d'un client et recevoir ses euros en USDC.

Un IBAN est un compte bancaire européen en euros, ouvert au nom de l'un de vos clients. Les euros qui y sont versés sont convertis en USDC et envoyés sur le portefeuille que vous indiquez à la création. Ils ne passent pas par vos soldes Loov.

Les IBAN réels nécessitent un compte approuvé et une clé réelle. Avec une clé de test, rien n'est ouvert : vous faites avancer le compte vous-même (voir « Tester » plus bas).

Les étapes

Vous créez le client. La réponse contient customer_id et kyc_link.
Votre client ouvre kyc_link et prouve son identité (pièce d'identité et selfie).
Une fois l'identité approuvée, le compte est demandé automatiquement.
Quand la banque l'ouvre, le compte passe à approved et porte un IBAN et un BIC.
Chaque versement vous est notifié, puis à nouveau lorsqu'il est terminé.

Créer un client

curl -X POST https://api.secure.payment.loov-solutions.com/v2/ibans \
  -H "Authorization: Bearer $LOOV_API_KEY" \
  -H "Idempotency-Key: 6f1c2b9e-order-42" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Awa Diop",
  "email": "awa@example.com",
  "type": "individual",
  "wallet_address": "0x7db946c37B240FC9Fa979927bafc5b2043B30d0A",
  "webhook_url": "https://example.com/webhooks/ibans"
}'

Champ	Type	Description
`name`	string	Nom complet du client, ou raison sociale.
`email`	string	E-mail du client.
`type`	string	Facultatif. individual (par défaut) ou business.
`wallet_address`	string	Adresse du portefeuille qui reçoit les USDC, sur le réseau Base (0x…). Elle ne peut pas être changée ensuite.
`webhook_url`	string	Facultatif. Adresse HTTPS appelée à chaque étape et à chaque versement.

{
  "customer_id": "cus_9f2c41d7",
  "status": "pending",
  "livemode": true,
  "type": "individual",
  "name": "Awa Diop",
  "email": "awa@example.com",
  "currency": "EUR",
  "kyc_link": "https://compose.finance/kyc/…",
  "wallet": {
    "address": "0x7db946c37B240FC9Fa979927bafc5b2043B30d0A",
    "chain": "base"
  },
  "account": null,
  "balance": "0",
  "balance_currency": "USDC",
  "webhook_url": "https://example.com/webhooks/ibans",
  "created_at": "2026-10-07T09:12:00+00:00"
}

Statuts

Statut	Étape	Description
`pending`	1	Client créé ; l'identité n'a pas encore été envoyée.
`kyc_submitted`	2	Identité envoyée, en cours d'examen.
`kyc_rejected`	—	Identité refusée. Demandez un nouveau lien et recommencez.
`kyc_approved`	3	Identité approuvée ; le compte est en cours de demande.
`iban_pending`	4	Compte demandé à la banque.
`iban_rejected`	—	La banque a refusé d'ouvrir le compte.
`approved`	5	Compte actif : l'objet account contient l'IBAN et le BIC.

Consulter un compte

curl -X GET https://api.secure.payment.loov-solutions.com/v2/ibans/cus_9f2c41d7 \
  -H "Authorization: Bearer $LOOV_API_KEY" \
  -H "Accept: application/json"

{
  "customer_id": "cus_9f2c41d7",
  "status": "approved",
  "account": {
    "iban": "FR7630006000011234567890189",
    "bic": "AGRIFRPP",
    "account_name": "Awa Diop",
    "account_number": "12345678901",
    "bank_name": "Banque partenaire",
    "bank_country": "FR",
    "bank_address": "…"
  },
  "balance": "1154.93",
  "balance_currency": "USDC"
}

Méthode	Adresse	Description
`GET`	/v2/ibans	Liste de vos comptes, du plus récent au plus ancien.
`GET`	/v2/ibans/{customer_id}	Un compte, avec son solde.
`POST`	/v2/ibans/{customer_id}/kyc-link	Un nouveau lien de vérification d'identité, si le précédent a expiré.
`GET`	/v2/ibans/{customer_id}/transactions	Les versements et retraits du compte.

Versements et frais

Pour chaque versement, source_amount est le montant reçu en euros et amount ce qui est arrivé en USDC sur votre portefeuille : le montant converti, moins les frais Loov (fee). C'est amount qui est compté sur le solde du compte. provider_fee est le prélèvement de notre partenaire bancaire, exprimé dans la devise d'origine (provider_fee_currency). Le solde est un cumul de ce qui a été reçu et non retiré : les USDC eux-mêmes sont sur votre portefeuille.

{
  "id": "01k7a2m4p6q8r0s2t4v6w8x0y2",
  "type": "deposit",
  "status": "completed",
  "provider_transaction_id": "txn_abc123",
  "source_amount": "1000",
  "source_currency": "EUR",
  "amount": "1154.93",
  "currency": "USDC",
  "exchange_rate": "1.1691279887",
  "fee": "2.5",
  "provider_fee": "1",
  "provider_fee_currency": "EUR",
  "bank_reference": "FLGVNY3H9F",
  "tx_hash": "0x1234…cdef",
  "created_at": "2026-10-07T10:02:00+00:00"
}

Statut	Compté	Description
`processing`	Non	Versement reçu, conversion en cours.
`completed`	Oui	Les USDC ont été envoyés sur votre portefeuille (tx_hash).
`failed`	Non	Le versement a échoué.
`cancelled`	Non	Le versement a été annulé.
`expired`	Non	Le versement n'a pas abouti à temps.
`reversed`	Retiré	Le versement a été renvoyé à l'expéditeur ; s'il avait été compté, il est retiré du solde.

Notifications

Si vous avez donné un webhook_url, nous l'appelons à chaque étape. La requête est signée comme les autres notifications (en-tête Loov-Signature, avec le secret de votre application).

Événement	Quand	Description
`iban.kyc.submitted`	Identité envoyée	Le client a terminé le parcours de vérification.
`iban.kyc.approved`	Identité approuvée	Le compte est demandé dans la foulée.
`iban.kyc.rejected`	Identité refusée	Demandez un nouveau lien.
`iban.virtual_account.created`	Compte demandé	La banque examine la demande.
`iban.virtual_account.approved`	Compte actif	data.iban.account contient l'IBAN.
`iban.virtual_account.rejected`	Compte refusé	La banque a refusé.
`iban.deposit.created`	Versement reçu	data.transaction décrit le versement.
`iban.deposit.status_changed`	Versement mis à jour	status vaut completed lorsqu'il est compté sur le solde.
`iban.withdrawal.created`	Retrait créé	data.transaction décrit le retrait.
`iban.withdrawal.status_changed`	Retrait mis à jour	Retiré du solde une fois terminé.
`iban.withdrawal_bank.*`	Compte de retrait	created, approved ou rejected : le compte bancaire vers lequel vont les retraits.

{
  "event": "iban.deposit.status_changed",
  "data": {
    "iban": {
      "customer_id": "cus_9f2c41d7",
      "status": "approved",
      "balance": "1154.93",
      "balance_currency": "USDC"
    },
    "transaction": {
      "type": "deposit",
      "status": "completed",
      "source_amount": "1000",
      "source_currency": "EUR",
      "amount": "1154.93",
      "currency": "USDC",
      "fee": "2.5"
    }
  }
}

Tester

Avec une clé de test, le client est créé chez nous seulement. Faites-le avancer avec l'adresse de simulation ; chaque appel déclenche la notification correspondante.

curl -X POST https://api.secure.payment.loov-solutions.com/v2/test/ibans/{customer_id}/simulate \
  -H "Authorization: Bearer $LOOV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "outcome": "deposit",
  "amount": 250
}'

outcome	Effet	Description
`kyc_submitted`	kyc_submitted	Identité envoyée.
`kyc_approved`	iban_pending	Identité approuvée, compte demandé.
`kyc_rejected`	kyc_rejected	Identité refusée.
`iban_approved`	approved	Compte actif, avec un IBAN de test.
`iban_rejected`	iban_rejected	Compte refusé.
`deposit`	—	Un versement terminé du montant indiqué (amount, 100 par défaut).

Erreurs fréquentes

Code	HTTP	Description
`account_not_active`	403	Votre compte doit être approuvé pour ouvrir des IBAN réels.
`wallet_address_required`	422	Aucune adresse de portefeuille n'a été fournie.
`provider_declined`	422	Notre partenaire bancaire a refusé la demande ; le message précise pourquoi.
`provider_unavailable`	503	Notre partenaire bancaire ne répond pas. Réessayez.
`ibans_unavailable`	503	Les IBAN ne sont pas disponibles pour le moment.