Create refund
Create refund
Overview
Create refund
Refunds a completed transaction on card, Wave, or MTN MoMo. Merchant balance updates immediately when the refund is recorded.
When to use this
Use for buyer reversals on eligible completed transactions; supports full and partial amounts.
Good to know
Card: customer credit on the card network is completed separately by operations. Wave partial: requires a customer phone on file (beneficiary payout). MTN MoMo live: the original payment must have a provider reference (RequestToPay UUID stored as provider_checkout_id); lomi. calls the MTN Disbursement refund API and polls until completion. MTN MoMo test: ledger-only; no MTN API call. Partial MTN refunds also require a customer phone on file. For subscription-linked payments, pass optional subscription_action: default (cancel on initial full refund, pause on renewal full refund), cancel, pause, or none. Partial refunds never change the subscription unless the cumulative refund reaches the full transaction amount.
See also
List refunds · Retrieve transaction · Refunds guide
Authentication
Merchant routes require an API key in the X-API-KEY header (see Integration overview). Use a test key against https://sandbox.api.lomi.africa and a live key against https://api.lomi.africa.
Endpoint
POST /refunds
Base URLs:
https://sandbox.api.lomi.africahttps://api.lomi.africa
Request
Path parameters
No path parameters beyond the URL pattern.
Query parameters
No query parameters.
Headers
| Name | In | Required | Schema | Description |
|---|---|---|---|---|
Lomi-Account | header | No | - | Optional lomi. Network account id (acct_...). When present, the API key acts as the Operator and the request targets the connected Member Account. |
Request body
JSON request payload.
Schema: CreateRefundDto
| Field | Required | Type | Description |
|---|---|---|---|
transaction_id | Yes | string | UUID of a completed transaction (card, Wave, or MTN MoMo) |
amount | Yes | number | Amount to refund (same currency as the transaction) |
reason | No | string | Reason for the refund |
refund_type | No | enum ("full", "partial") | Full or partial refund. If omitted, full when amount equals transaction gross amount. |
subscription_action | No | enum ("default", "cancel", "pause", ...) | Subscription side-effect after a full refund: default (cancel initial payment, pause renewal), cancel, pause, or none. |
Example body:
{
"transaction_id": "string",
"amount": 0
}Responses
| Status | Description |
|---|---|
201 | Created successfully |
400 | Bad request, invalid or missing parameters |
Errors
Errors follow the standard JSON error format (status code and machine-readable message). Validate inputs before calling; 401 indicates a missing/invalid key, 404 a missing resource for this organization, 429 rate limiting. For safe retries on create-style calls, send an idempotency key when your flow supports it.
Example
curl -sS -X POST "https://sandbox.api.lomi.africa/refunds" \
-H "X-API-KEY: $LOMI_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"transaction_id":"string","amount":0}'OpenAPI
- operationId:
RefundsController_create - Operation:
POST /refunds
Full schemas and Try it: API reference. Machine-readable contract: repo apps/docs/openapi.json.