Wallet-as-a-Service (sous-portefeuilles)

Le module Wallet-as-a-Service (WaaS) vous permet de créer un sous-portefeuille par utilisateur final : chacun reçoit ses propres adresses de dépôt permanentes, un solde par actif, et vous pilotez retraits et transferts par API.

Toutes les routes ci-dessous sont authentifiées par clé API (scopes accounts:read / accounts:write). Voir Authentification.

Modèle

Un sous-portefeuille (WalletAccount) appartient à votre compte marchand et représente un de vos utilisateurs (libellé + externalRef = votre identifiant interne).
Les fonds des utilisateurs sont ségrégués de votre balance opérationnelle (comptabilité séparée). Vous ne pouvez pas retirer les fonds d’un sous-portefeuille via votre wallet principal.
Attribution des dépôts selon la chaîne :
- UTXO (BTC) → adresse dérivée unique par sous-portefeuille → attribution automatique.
- Chaînes à mémo (XRP, TON, XLM…) → adresse partagée + tag/mémo unique par sous-portefeuille → attribution automatique.
- EVM / account (BEP20, ERC20, Polygon, Solana) → adresse canonique partagée au niveau marchand → un dépôt EVM n’est pas attribuable automatiquement à un sous-portefeuille.

Créer un sous-portefeuille

curl -X POST https://api.pay.izichange.com/v1/accounts \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Jean Dupont", "externalRef": "user_10293", "email": "jean@exemple.com" }'

{ "id": "0ca3930e-…", "label": "Jean Dupont", "externalRef": "user_10293", "status": "active", "createdAt": "…" }

Champ	Requis	Sens
`label`	oui	Nom lisible du sous-portefeuille.
`externalRef`	non	Votre identifiant utilisateur (unique chez vous) — repris dans les webhooks.
`email`, `phoneNumber`	non	Métadonnées facultatives.

Obtenir une adresse de dépôt

L’adresse est permanente par (sous-portefeuille, actif) — appelez autant de fois que voulu, elle ne change pas.

curl https://api.pay.izichange.com/v1/accounts/{id}/addresses/USDT.BEP20 \
  -H "Authorization: Bearer $API_KEY"

{ "address": "0x3bcB16…bF99", "assetCode": "USDT.BEP20", "memo": null, "memoType": null, "shared": true }

shared: true = adresse EVM partagée (voir attribution ci-dessus). Pour une attribution dédiée, utilisez une chaîne UTXO ou à mémo (memo non nul).

Autres routes

Méthode	Route	Scope	Description
`GET`	`/v1/accounts`	`accounts:read`	Liste paginée des sous-portefeuilles.
`GET`	`/v1/accounts/{id}`	`accounts:read`	Détail + soldes par actif.
`GET`	`/v1/accounts/{id}/balances`	`accounts:read`	Soldes par actif.
`GET`	`/v1/accounts/{id}/addresses`	`accounts:read`	Adresses générées du sous-portefeuille.
`GET`	`/v1/accounts/{id}/transactions`	`accounts:read`	Historique d’un sous-portefeuille.
`GET`	`/v1/accounts/transactions`	`accounts:read`	Flux consolidé de tous vos sous-portefeuilles.
`PATCH`	`/v1/accounts/{id}`	`accounts:write`	Mettre à jour (libellé, statut…).
`POST`	`/v1/accounts/{id}/payouts`	`accounts:write`	Retrait on-chain depuis le sous-portefeuille.
`POST`	`/v1/accounts/{id}/transfers`	`accounts:write`	Transfert interne (vers un autre sous-portefeuille ou votre balance opérationnelle).

Retrait depuis un sous-portefeuille

curl -X POST https://api.pay.izichange.com/v1/accounts/{id}/payouts \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{ "assetCode": "USDT.BEP20", "amount": "50", "destinationAddress": "0x…" }'

Webhooks WaaS

Abonnez un endpoint aux événements suivants (voir Webhooks) :

Événement	Déclenchement
`wallet_account.deposit.completed`	Un dépôt crédité sur un sous-portefeuille.
`wallet_account.payout.confirmed`	Un retrait on-chain confirmé.
`wallet_account.transfer.completed`	Un transfert interne effectué.

Exemple de payload (wallet_account.deposit.completed) :

{
  "event": "wallet_account.deposit.completed",
  "timestamp": 1731843299,
  "data": {
    "payinId": "…",
    "merchantId": "…",
    "walletAccountId": "0ca3930e-…",
    "externalRef": "user_10293",
    "assetCode": "USDT.BEP20",
    "amountGross": "100", "amountNet": "99", "feeAmount": "1",
    "txid": "0x…"
  }
}

externalRef vous permet de rattacher le dépôt à votre utilisateur sans stocker la correspondance walletAccountId de votre côté.

Démarrage

Guides d'intégration

Intégration API

Webhooks