API - Portefeuille virtuel

Les conventions générales s'appliquent : en-têtes, enveloppe de réponse, pagination et codes d'erreur.

Périmètre

Vous ne pouvez consulter et modifier que vos propres portefeuilles virtuels. Toute action sur le portefeuille d'un autre compte renvoie 403.

Créer un portefeuille

POST /api/public/v1/wallets/store

Paramètres

Champ	Type	Obligatoire	Description
phone	string	Oui	Numéro du titulaire. Unique sur la plateforme.
last_name	string	Oui	Nom du titulaire, 100 caractères maximum.
first_name	string	Non	Prénom du titulaire.
city	string	Oui	Ville de résidence.
address	string	Oui	Adresse complète.
company	string	Oui	Entité juridique exploitant le portefeuille.
cash_out	objet	Oui	Configuration de retrait par défaut.
cash_out.info.name	string	Oui	Nom du bénéficiaire du versement.
cash_out.info.phone	string	Oui	Numéro du bénéficiaire, pour un versement mobile money.
cash_out.info.rib	string	Non	RIB, pour un versement bancaire.
cash_out.info.first_choice	string	Oui	Canal par défaut : mobile_money ou bank_transfer. Ce vocabulaire est propre au portefeuille : le calcul de frais attend, lui, un nom d'opérateur.
cash_out.info.description	string	Non	Instructions complémentaires, 100 caractères maximum.

cash_out détermine la destination des retraits

Cette configuration n'est pas décorative : c'est elle qui définit où partiront les fonds lors d'un retrait. La demande de retrait, elle, ne prend aucune destination en paramètre.

Exemple

curl --request POST \
    "https://efn.efaina.com/api/public/v1/wallets/store" \
    --header "Authorization: Bearer VOTRE_TOKEN" \
    --header "Accept: application/json" \
    --form "phone=0341234567" \
    --form "last_name=Randria" \
    --form "first_name=Lova" \
    --form "city=Antananarivo" \
    --form "address=Lot II B 23" \
    --form "company=MyCompany SARL" \
    --form "cash_out[info][name]=Randria Lova" \
    --form "cash_out[info][phone]=0341234567" \
    --form "cash_out[info][first_choice]=mobile_money"

Champs ignorés

Seuls les champs listés ci-dessus sont pris en compte. Tout autre champ envoyé est silencieusement ignoré — il n'est ni stocké, ni signalé en erreur.

Erreurs spécifiques

Code	Cas
422 sur phone	Le numéro est déjà utilisé par un autre portefeuille.
422	Le nombre maximum de portefeuilles autorisé par votre formule est atteint.

Mettre à jour un portefeuille

PUT /api/public/v1/wallets/{wallet}/update

Mêmes champs qu'à la création, tous facultatifs : seuls ceux transmis sont modifiés. C'est par cet endpoint que l'on change la destination des retraits, en renvoyant un objet cash_out complet.

Consulter un portefeuille

GET /api/public/v1/wallets/{wallet}/show

Deux champs à lire avec précaution

La représentation d'un portefeuille comporte deux typages contre-intuitifs, aussi bien sur cet endpoint que dans le data de la liste :

Champ	Type renvoyé	À prévoir
config	chaîne JSON, pas objet	Un premier décodage donne la chaîne, un second l'objet contenant cash_out. Prévoyez ce double décodage avant de lire la configuration de retrait.
balance	chaîne décimale, par exemple "0.00"	Les montants sont des entiers partout ailleurs dans l'API. Convertissez explicitement, sans compter sur un typage numérique.

L'opérateur de retrait est déduit du numéro

Si vous renseignez cash_out.info.first_choice à mobile_money sans préciser l'opérateur, celui-ci est déduit du préfixe du numéro de téléphone : un 034 donne MVOLA dans la configuration enregistrée. Relisez le portefeuille après création si vous avez besoin de connaître la valeur retenue.

Lister les portefeuilles

GET /api/public/v1/wallets

Résultat paginé, avec les filtres communs.

Création en masse

POST /api/public/v1/wallets/mass/store

Champ	Type	Obligatoire	Description
items	tableau	Oui	Portefeuilles à créer, 50 maximum par appel. Chaque entrée reprend les champs de la création unitaire.

La réponse est un 202 : le lot est mis en file et traité de façon asynchrone. Elle contient un batch_id à conserver.

Le suivi se fait de deux manières :

• les évènements wallet.mass.completed et wallet.mass.failed de votre webhook ;
• l'endpoint de rapports ci-dessous.

Rapports d'import

GET /api/public/v1/wallets/import-reports

Historique des lots d'import de portefeuilles, avec leur batch_id, leur volume et les erreurs éventuelles ligne par ligne.

Référence complète

Référence API générée.