Payouts

Use POST /payouts for all outbound money movement.

destination: "self": withdraw to a registered payout method on your organization (payout_method_id required). Supports bank, spi, wave, and mtn (mobile money).
destination: "beneficiary": pay a third party on mobile rails (wave or mtn). Requires recipient.name and recipient.phone (any E.164 mobile number; not tied to payout_method_id). Bank payouts to arbitrary accounts are not supported.

Wave and MTN payouts require a live API key (lomi_sk_live_…). Test keys return 400 for mobile-money payouts, no real provider transfer is initiated.

SPI settlement for self payouts continues asynchronously after the RPC succeeds. SPI beneficiary payouts are ledger-only until SPI execution ships.

Create a payout

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

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

// Withdraw to your registered Wave mobile money method
await lomi.payouts.create({
  destination: 'self',
  rail: 'wave',
  amount: 50000,
  currency_code: 'XOF',
  payout_method_id: '550e8400-e29b-41d4-a716-446655440000',
});

// Pay a contractor via Wave
await lomi.payouts.create({
  destination: 'beneficiary',
  rail: 'wave',
  amount: 10000,
  currency_code: 'XOF',
  recipient: { name: 'Ada Lovelace', phone: '+221771234567' },
  reason: 'Invoice #12',
});

curl -X POST "https://api.lomi.africa/payouts" \
  -H "X-API-KEY: $LOMI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "beneficiary",
    "rail": "wave",
    "amount": 10000,
    "currency_code": "XOF",
    "recipient": { "name": "Ada Lovelace", "phone": "+221771234567" }
  }'

Payload reference

Field	Type	Required
`destination`	`'self'` \| `'beneficiary'`	Yes
`rail`	`'wave'` \| `'spi'` \| `'bank'` \| `'mtn'`	Yes
`amount`	`number`	Yes
`currency_code`	`string`	Yes
`payout_method_id`	UUID	Yes for `self`; required for beneficiary `spi`
`recipient`	`{ name, phone }`	Yes for beneficiary `wave`
`reason`	`string`	No

List and get

GET /payouts, withdrawals and beneficiary payouts (each row includes kind). Test API keys list test withdrawals only; live beneficiary payout rows are omitted.
GET /payouts/{id}, resolves merchant withdrawals and beneficiary payouts by ID (org-scoped).

Payout blocked by platform risk controls

Large or high-velocity withdrawals may be held automatically. If POST /payouts fails with a risk-related error, wait and try again later or contact support.

For incoming payment risk screening (card and mobile money charges), see lomi. Radar.

Payouts

Create a payout

Payload reference

List and get

Payout blocked by platform risk controls

On this page