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.
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

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.