Virements bénéficiaires

Envoyez des paiements à des prestataires, fournisseurs et autres bénéficiaires.

L’API Beneficiary Payouts permet d’envoyer des paiements depuis le solde de votre compte vers des tiers (prestataires, fournisseurs, salariés, etc.).

Utilisez Payouts pour retirer vers vos propres comptes et Beneficiary Payouts pour payer des tiers.

Cycle de vie, plafonds et modes d’échec : Cycle de vie des virements.

Initier un virement bénéficiaire

Envoie un paiement vers un bénéficiaire externe.

Corps de la requête

Champ	Type	Obligatoire	Description
`amount`	`number`	Oui	Montant envoyé
`currency_code`	`string`	Oui	Devise (`XOF`, `USD`, etc.)
`beneficiary_phone`	`string`	Oui	Numéro du destinataire
`beneficiary_name`	`string`	Non	Nom du destinataire
`provider_code`	`string`	Non	Prestataire (ex. `WAVE`)
`description`	`string`	Non	Description du paiement
`metadata`	`object`	Non	Métadonnées

import { LomiSDK } from '@lomi./sdk';

const lomi = new LomiSDK({
  apiKey: process.env.LOMI_API_KEY!,
  environment: 'live',
});

const payout = await lomi.beneficiaryPayouts.create({
  amount: 50000,
  currency_code: 'XOF',
  beneficiary_phone: '+221771234567',
  beneficiary_name: 'Amadou Ba',
  provider_code: 'WAVE',
  description: 'Paiement prestataire – janvier',
  metadata: {
    invoice_id: 'INV-2024-001',
  },
});

console.log(`Payout sent: ${payout.id}, Status: ${payout.status}`);

from lomi import LomiClient
import os

client = LomiClient(
    api_key=os.environ["LOMI_API_KEY"],
    environment="test"
)

payout = client.beneficiary_payouts.create({
    "amount": 50000,
    "currency_code": "XOF",
    "beneficiary_phone": "+221771234567",
    "beneficiary_name": "Amadou Ba",
    "provider_code": "WAVE",
    "description": "Paiement prestataire – janvier",
    "metadata": {"invoice_id": "INV-2024-001"}
})

print(f"Payout sent: {payout['id']}")

curl -X POST "https://api.lomi.africa/beneficiary-payouts" \
  -H "X-API-KEY: $LOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency_code": "XOF",
    "beneficiary_phone": "+221771234567",
    "beneficiary_name": "Amadou Ba",
    "provider_code": "WAVE",
    "description": "Paiement prestataire – janvier",
    "metadata": {"invoice_id": "INV-2024-001"}
  }'

Lister les virements bénéficiaires

Récupère les virements avec filtrage optionnel.

Paramètres de requête

Paramètre	Type	Description
`statuses`	`string`	Statuts séparés par virgules : `pending`, `completed`, `failed`
`startDate`	`string`	À partir de (ISO 8601)
`endDate`	`string`	Jusqu’à (ISO 8601)
`currencyCode`	`string`	Filtrer par devise
`limit`	`number`	Par page (défaut : `50`)
`offset`	`number`	Décalage (défaut : `0`)

const payouts = await lomi.beneficiaryPayouts.list({
  statuses: 'completed',
  currencyCode: 'XOF',
  startDate: '2024-01-01T00:00:00Z',
  limit: 20,
});

payouts = client.beneficiary_payouts.list(
    statuses="completed",
    currencyCode="XOF",
    limit=20
)

curl -X GET "https://api.lomi.africa/beneficiary-payouts?statuses=completed&currencyCode=XOF&limit=20" \
  -H "X-API-KEY: $LOMI_API_KEY"

Obtenir un virement bénéficiaire

Récupère le détail d’un virement.

const payout = await lomi.beneficiaryPayouts.get('bp_abc123...');
console.log(`Status: ${payout.status}`);

payout = client.beneficiary_payouts.get('bp_abc123...')

curl -X GET "https://api.lomi.africa/beneficiary-payouts/bp_abc123..." \
  -H "X-API-KEY: $LOMI_API_KEY"

Objet Beneficiary Payout

Champ	Type	Description
`id`	`string`	Identifiant unique
`amount`	`number`	Montant
`fee_amount`	`number`	Frais prélevés
`net_amount`	`number`	Montant reçu par le bénéficiaire
`currency_code`	`string`	Devise
`status`	`string`	`pending`, `completed`, `failed`
`beneficiary_phone`	`string`	Téléphone destinataire
`beneficiary_name`	`string`	Nom
`provider_code`	`string`	Prestataire
`description`	`string`	Description
`failure_reason`	`string`	Motif d’échec
`metadata`	`object`	Métadonnées
`created_at`	`string`	Création

Webhooks

Événement	Description
`beneficiary_payout.pending`	Virement initié
`beneficiary_payout.completed`	Virement livré
`beneficiary_payout.failed`	Échec

Réponses d’erreur

Statut	Description
`400`	Entrée invalide ou solde insuffisant
`401`	Clé API invalide ou manquante
`404`	Virement introuvable

Virements bénéficiaires

Sur cette page