Payments
Payouts
Withdraw funds from your account balance.
The Payouts API allows you to withdraw funds from your merchant account balance to your bank account or mobile money.
Payouts are processed asynchronously. Use webhooks to track status (payout.completed or payout.failed).
Initiate a payout
Withdraw funds from your account balance.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | Yes | Amount to withdraw |
currency_code | string | Yes | Currency (XOF, USD, etc.) |
payout_method_id | string | Yes | Your payout method (bank/mobile money) |
description | string | No | Payout 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.payouts.create({
amount: 100000,
currency_code: 'XOF',
payout_method_id: 'pm_abc123...',
description: 'Monthly withdrawal',
});
console.log(`Payout initiated: ${payout.id}, Status: ${payout.status}`);from lomi import LomiClient
import os
client = LomiClient(
api_key=os.environ["LOMI_API_KEY"],
environment="test"
)
payout = client.payouts.create({
"amount": 100000,
"currency_code": "XOF",
"payout_method_id": "pm_abc123...",
"description": "Monthly withdrawal"
})
print(f"Payout initiated: {payout['id']}")curl -X POST "https://api.lomi.africa/payouts" \
-H "X-API-KEY: $LOMI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 100000,
"currency_code": "XOF",
"payout_method_id": "pm_abc123...",
"description": "Monthly withdrawal"
}'List payouts
Retrieve all payouts with optional filtering.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
statuses | string | Comma-separated statuses: pending, completed, failed |
startDate | string | Filter from this date (ISO 8601) |
endDate | string | Filter up to this date (ISO 8601) |
limit | number | Results per page (default: 50) |
offset | number | Pagination offset (default: 0) |
const payouts = await lomi.payouts.list({
statuses: 'completed',
startDate: '2024-01-01T00:00:00Z',
limit: 20,
});payouts = client.payouts.list(
statuses="completed",
startDate="2024-01-01T00:00:00Z",
limit=20
)curl -X GET "https://api.lomi.africa/payouts?statuses=completed&limit=20" \
-H "X-API-KEY: $LOMI_API_KEY"Get a payout
Retrieve details of a specific payout.
const payout = await lomi.payouts.get('po_abc123...');
console.log(`Status: ${payout.status}`);payout = client.payouts.get('po_abc123...')curl -X GET "https://api.lomi.africa/payouts/po_abc123..." \
-H "X-API-KEY: $LOMI_API_KEY"Payout Object
| Field | Type | Description |
|---|---|---|
id | string | Unique payout identifier |
amount | number | Payout amount |
currency_code | string | Currency code |
status | string | pending, completed, failed |
payout_method_id | string | Payout destination |
description | string | Description |
failure_reason | string | Reason for failure (if failed) |
provider_code | string | Payment provider |
metadata | object | Custom metadata |
created_at | string | Creation timestamp |
Webhooks
| Event | Description |
|---|---|
payout.pending | Payout initiated |
payout.completed | Payout successfully processed |
payout.failed | Payout failed |
Error Responses
| Status | Description |
|---|---|
400 | Invalid input or insufficient balance |
401 | Invalid or missing API key |
404 | Payout not found |