RefundsOverview

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

FlowAvailabilityAmount ruleDestination
USD cardFull and partial refundsSupply amount for a partial refund; omit it for a full refund.Original card
Standard NGN bank transferFull refunds onlyOmit 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 fee

For a standard NGN bank-transfer refund:

NGN total fee = original transaction fee + configured refund fee
total_reserved = refund principal + total fee

Illustrative NGN Fee Example

ItemAmount
Actual amount receivedNGN 50,000.00
Original transaction feeNGN 150.00
Configured refund feeNGN 100.00
Total feeNGN 250.00
Total requiredNGN 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.

  1. Available wallet balance is reserved first.
  2. Any remaining requirement is held from eligible pending balance.
  3. 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

  1. The merchant requests a refund.
  2. SaySwitch reserves available balance first.
  3. Any remaining requirement is held from eligible pending balance.
  4. The refund returns awaiting_settlement when pending funding is needed.
  5. As settlements occur, settled money funds the refund hold before any remainder is added to available balance.
  6. Once completely funded, the refund changes to pending.
  7. Processing begins according to the refund flow.
  8. 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

StatusMeaning
awaiting_settlementWaiting for reserved pending funds to settle.
pendingFully funded and queued for processing.
processingRefund processing has started.
successThe refund completed successfully.
failedA processing attempt failed; reserved funds remain protected.
rejectedThe 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.

FieldDescription
refund_referenceSaySwitch reference for the refund.
transaction_referenceReference of the original transaction.
amountRefund principal returned to the customer.
feeTotal refund fee.
fee_breakdown.original_transaction_feeOriginal transaction fee included in the refund cost. Usually 0.00 for USD card refunds.
fee_breakdown.configured_refund_feeRefund fee configured for the merchant.
fee_breakdown.total_feeSum of the fee components; matches fee.
total_reservedRefund principal plus total fee.
currencyRefund currency.
statusCurrent refund processing status.
channelcard or bank_transfer.
processing_modemanual for USD cards or automatic for NGN bank transfers.
external_referenceProcessing reference when available.
requested_atTime the request was accepted.
completed_atCompletion 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.

FieldDescription
funding.statusawaiting_settlement, funded, consumed, or released.
funding.available_reservedAmount reserved immediately from available balance.
funding.pending_reservedAmount reserved from eligible pending balance.
funding.pending_funded_amountPending reservation already funded through settlement.
funding.pending_remainingPending reservation still awaiting settlement.
funding.funded_atTime 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

  1. Initiate the refund from a secure backend with a unique Idempotency-Key.
  2. Store the returned refund_reference, refund status, and funding status.
  3. If the refund is awaiting_settlement, pending, or processing, wait for status updates instead of submitting it again.
  4. Verify refund webhook signatures using the raw request body and process events idempotently.
  5. Verify the refund status before treating it as complete.

API Reference

TaskEndpointDocumentation
Initiate a refundPOST /api/v1/refundInitiate a Refund
List refundsGET /api/v1/refundGet Refunds
Verify a refundGET /api/v1/refund/status/{refund_reference}Get Refund Details
Check wallet balanceGET /api/v1/wallet_balance/{currency}Get Wallet Balance
Receive status updatesConfigured webhook URLRefund Webhooks

Refund API requests must come from a secure merchant backend. Keep secret keys out of frontend code and logs.