Payments
Beneficiary Payouts
Send payments to contractors, suppliers, and other beneficiaries.
The Beneficiary Payouts API allows you to send payments from your account balance to external parties (contractors, suppliers, employees, etc.).
Use Payouts for withdrawing to your own accounts, and Beneficiary Payouts for paying external parties.
Initiate a beneficiary payout
Send a payment to an external beneficiary.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | Yes | Amount to send |
currency_code | string | Yes | Currency (XOF, USD, etc.) |
beneficiary_phone | string | Yes | Recipient phone number |
beneficiary_name | string | No | Recipient name |
provider_code | string | No | Payment provider (e.g., WAVE) |
description | string | No | Payment description |
metadata | object | No | Custom key-value pairs |
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: 'Contractor payment - January',
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": "Contractor payment - January",
"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": "Contractor payment - January",
"metadata": {"invoice_id": "INV-2024-001"}
}'List beneficiary payouts
Retrieve all beneficiary payouts with optional filtering.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
statuses | string | Comma-separated: pending, completed, failed |
startDate | string | Filter from this date (ISO 8601) |
endDate | string | Filter up to this date (ISO 8601) |
currencyCode | string | Filter by currency |
limit | number | Results per page (default: 50) |
offset | number | Pagination offset (default: 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¤cyCode=XOF&limit=20" \
-H "X-API-KEY: $LOMI_API_KEY"Get a beneficiary payout
Retrieve details of a specific beneficiary payout.
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"Beneficiary Payout Object
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier |
amount | number | Payout amount |
fee_amount | number | Fee deducted |
net_amount | number | Amount received by beneficiary |
currency_code | string | Currency |
status | string | pending, completed, failed |
beneficiary_phone | string | Recipient phone |
beneficiary_name | string | Recipient name |
provider_code | string | Payment provider |
description | string | Description |
failure_reason | string | Reason for failure |
metadata | object | Custom metadata |
created_at | string | Creation timestamp |
Webhooks
| Event | Description |
|---|---|
beneficiary_payout.pending | Payout initiated |
beneficiary_payout.completed | Payout delivered |
beneficiary_payout.failed | Payout failed |
Error Responses
| Status | Description |
|---|---|
400 | Invalid input or insufficient balance |
401 | Invalid or missing API key |
404 | Payout not found |