Payments
Refunds
Process full or partial refunds for transactions.
The Refunds API allows you to refund completed transactions. Refunds are processed asynchronously by the original payment provider.
Refunds are initiated immediately but processed asynchronously. Use webhooks to track final status (refund.completed or refund.failed).
Initiate a refund
Issue a full or partial refund for a completed transaction.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
transaction_id | string | Yes | ID of the transaction to refund |
amount | number | No | Refund amount (full refund if omitted) |
reason | string | No | Reason for the refund |
metadata | object | No | Custom key-value pairs |
import { LomiSDK } from '@lomi./sdk';
const lomi = new LomiSDK({
apiKey: process.env.LOMI_API_KEY!,
environment: 'live',
});
// Full refund
const fullRefund = await lomi.refunds.create({
transaction_id: 'tx_abc123...',
reason: 'Customer requested refund',
});
// Partial refund
const partialRefund = await lomi.refunds.create({
transaction_id: 'tx_abc123...',
amount: 5000,
reason: 'Partial product return',
metadata: {
ticket_id: 'TICKET-456',
},
});
console.log(`Refund initiated: ${partialRefund.id}, Status: ${partialRefund.status}`);from lomi import LomiClient
import os
client = LomiClient(
api_key=os.environ["LOMI_API_KEY"],
environment="test"
)
refund = client.refunds.create({
"transaction_id": "tx_abc123...",
"amount": 5000,
"reason": "Customer requested refund",
"metadata": {"ticket_id": "TICKET-456"}
})
print(f"Refund initiated: {refund['id']}, Status: {refund['status']}")curl -X POST "https://api.lomi.africa/refunds" \
-H "X-API-KEY: $LOMI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"transaction_id": "tx_abc123...",
"amount": 5000,
"reason": "Customer requested refund",
"metadata": {"ticket_id": "TICKET-456"}
}'List refunds
Retrieve all refunds with optional filtering.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
status | string | Filter by status: pending, completed, failed, cancelled |
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 refunds = await lomi.refunds.list({
status: 'completed',
startDate: '2024-01-01T00:00:00Z',
limit: 20,
});refunds = client.refunds.list(
status="completed",
startDate="2024-01-01T00:00:00Z",
limit=20
)curl -X GET "https://api.lomi.africa/refunds?status=completed&startDate=2024-01-01T00:00:00Z&limit=20" \
-H "X-API-KEY: $LOMI_API_KEY"Get a refund
Retrieve details of a specific refund.
const refund = await lomi.refunds.get('ref_abc123...');
console.log(`Status: ${refund.status}`);refund = client.refunds.get('ref_abc123...')curl -X GET "https://api.lomi.africa/refunds/ref_abc123..." \
-H "X-API-KEY: $LOMI_API_KEY"Refund Object
| Field | Type | Description |
|---|---|---|
id | string | Unique refund identifier |
transaction_id | string | Original transaction ID |
amount | number | Refund amount |
currency_code | string | Currency code |
status | string | pending, completed, failed, cancelled |
reason | string | Refund reason |
failure_reason | string | Reason for failure (if failed) |
provider_code | string | Payment provider |
metadata | object | Custom metadata |
created_at | string | Creation timestamp |
Webhooks
Subscribe to these events for refund status updates:
| Event | Description |
|---|---|
refund.pending | Refund initiated, awaiting provider |
refund.completed | Refund successfully processed |
refund.failed | Refund failed (check failure_reason) |
Error Responses
| Status | Description |
|---|---|
400 | Invalid input or amount exceeds transaction |
401 | Invalid or missing API key |
404 | Transaction or refund not found |