Refunds
SaySwitch refunds let merchants return an eligible payment to a customer. Refunds are asynchronous: an accepted request reserves the required funds, then moves through funding and processing before it is complete.
Current Availability
| Flow | Availability | Amount rule | Destination |
|---|---|---|---|
| USD card | Full and partial refunds | Supply amount for a partial refund; omit it for a full refund. | Original card |
| Standard NGN bank transfer | Full refunds only | Omit amount; SaySwitch calculates the refundable principal. | Verified originating bank account |
Dedicated-account credits are not supported by the automatic NGN bank-transfer refund flow.
Merchants cannot select or modify the destination of an NGN bank-transfer refund. They also cannot manually requery, reprocess, or change its status. SaySwitch support handles review and safe recovery when an automatic refund needs attention.
NGN Refund Principal
For a standard NGN bank-transfer refund, the principal is the actual amount received and recorded on the successful transaction. It is not the transaction’s requested_amount.
- An underpayment is refunded using the lower amount actually received.
- If an excess-payment refund completed successfully, that returned excess is subtracted from the remaining refundable principal.
- If a payment-difference refund is unresolved, a new full refund is blocked until that workflow is resolved.
- If the payment already has a full automatic reversal, another refund cannot be created.
Refund Fees
Refund fees are configured for each merchant agreement. Amounts shown in this documentation are examples, not fixed production prices.
For a USD card refund:
total fee = configured USD card refund fee
total_reserved = refund principal + total feeFor a standard NGN bank-transfer refund:
NGN total fee = original transaction fee + configured refund fee
total_reserved = refund principal + total feeIllustrative NGN Fee Example
| Item | Amount |
|---|---|
| Actual amount received | NGN 50,000.00 |
| Original transaction fee | NGN 150.00 |
| Configured refund fee | NGN 100.00 |
| Total fee | NGN 250.00 |
| Total required | NGN 50,250.00 |
Always use the values returned in fee_breakdown and total_reserved for the specific refund.
How Refund Funding Works
SaySwitch determines the funding split automatically. Merchants do not choose whether available or pending balance is used.
- Available wallet balance is reserved first.
- Any remaining requirement is held from eligible pending balance.
- The refund principal and total fee must both be covered.
The gross pending balance is not immediately reduced by a pending hold. Instead, the held amount is excluded from pending_available, which represents pending funds that remain spendable.
If available balance plus eligible pending balance cannot cover total_reserved, the API returns HTTP 422. No refund is created, no funds are reserved, and the wallet cannot become negative.
Settlement Lifecycle
- The merchant requests a refund.
- SaySwitch reserves available balance first.
- Any remaining requirement is held from eligible pending balance.
- The refund returns
awaiting_settlementwhen pending funding is needed. - As settlements occur, settled money funds the refund hold before any remainder is added to available balance.
- Once completely funded, the refund changes to
pending. - Processing begins according to the refund flow.
- SaySwitch sends webhook notifications as the status changes.
Do not submit another refund merely because the current refund is awaiting settlement or processing.
Refund Statuses
| Status | Meaning |
|---|---|
awaiting_settlement | Waiting for reserved pending funds to settle. |
pending | Fully funded and queued for processing. |
processing | Refund processing has started. |
success | The refund completed successfully. |
failed | A processing attempt failed; reserved funds remain protected. |
rejected | The refund was rejected and applicable reserves were released. |
Only success confirms that the customer was refunded. HTTP 202, awaiting_settlement, pending, processing, and failed are not successful completion.
For a failed automatic NGN refund, SaySwitch support may review, requery, or safely reprocess the existing refund. Merchants must not create a duplicate refund or attempt to change its status.
Common Refund Object
The initiate, list, and detail endpoints return the same refund structure. Refund webhooks use the same fields, with updated_at in place of completed_at where applicable.
| Field | Description |
|---|---|
refund_reference | SaySwitch reference for the refund. |
transaction_reference | Reference of the original transaction. |
amount | Refund principal returned to the customer. |
fee | Total refund fee. |
fee_breakdown.original_transaction_fee | Original transaction fee included in the refund cost. Usually 0.00 for USD card refunds. |
fee_breakdown.configured_refund_fee | Refund fee configured for the merchant. |
fee_breakdown.total_fee | Sum of the fee components; matches fee. |
total_reserved | Refund principal plus total fee. |
currency | Refund currency. |
status | Current refund processing status. |
channel | card or bank_transfer. |
processing_mode | manual for USD cards or automatic for NGN bank transfers. |
external_reference | Processing reference when available. |
requested_at | Time the request was accepted. |
completed_at | Completion time returned by API responses, or null before success. |
Funding Object
Refund status and funding.status describe different parts of the process. Refund status tracks processing, while funding status describes the reserved money.
| Field | Description |
|---|---|
funding.status | awaiting_settlement, funded, consumed, or released. |
funding.available_reserved | Amount reserved immediately from available balance. |
funding.pending_reserved | Amount reserved from eligible pending balance. |
funding.pending_funded_amount | Pending reservation already funded through settlement. |
funding.pending_remaining | Pending reservation still awaiting settlement. |
funding.funded_at | Time the refund became fully funded, or null while waiting. |
consumed means the reserved funds completed the refund. released means applicable reserves were returned after rejection.
Integration Flow
- Initiate the refund from a secure backend with a unique
Idempotency-Key. - Store the returned
refund_reference, refund status, and funding status. - If the refund is
awaiting_settlement,pending, orprocessing, wait for status updates instead of submitting it again. - Verify refund webhook signatures using the raw request body and process events idempotently.
- Verify the refund status before treating it as complete.
API Reference
| Task | Endpoint | Documentation |
|---|---|---|
| Initiate a refund | POST /api/v1/refund | Initiate a Refund |
| List refunds | GET /api/v1/refund | Get Refunds |
| Verify a refund | GET /api/v1/refund/status/{refund_reference} | Get Refund Details |
| Check wallet balance | GET /api/v1/wallet_balance/{currency} | Get Wallet Balance |
| Receive status updates | Configured webhook URL | Refund Webhooks |
Refund API requests must come from a secure merchant backend. Keep secret keys out of frontend code and logs.