RefundsGet Refund Details

Get Refund Details

Retrieve the current status of one USD card or standard NGN bank-transfer refund using its refund_reference.

See the Refund Overview for the funding and processing lifecycle.

Endpoint

GET https://backendapi.sayswitchgroup.com/api/v1/refund/status/{refund_reference}

Request Examples

curl --request GET \
  --url https://backendapi.sayswitchgroup.com/api/v1/refund/status/REFUND_REFERENCE \
  --header "Authorization: Bearer YOUR_SECRET_KEY" \
  --header "Accept: application/json"

Keep your secret key and this request on your server.

Response

{
  "success": true,
  "message": "Refund retrieved.",
  "data": {
    "refund_reference": "REF_NGN_2026_001",
    "transaction_reference": "NGN_TXN_2026_001",
    "amount": "50000.00",
    "fee": "250.00",
    "fee_breakdown": {
      "original_transaction_fee": "150.00",
      "configured_refund_fee": "100.00",
      "total_fee": "250.00"
    },
    "total_reserved": "50250.00",
    "funding": {
      "status": "consumed",
      "available_reserved": "50250.00",
      "pending_reserved": "0.00",
      "pending_funded_amount": "0.00",
      "pending_remaining": "0.00",
      "funded_at": "2026-10-24T10:05:00+01:00"
    },
    "currency": "NGN",
    "status": "success",
    "channel": "bank_transfer",
    "processing_mode": "automatic",
    "external_reference": "REFUND_PROCESSING_REFERENCE",
    "requested_at": "2026-10-24T10:00:00+01:00",
    "completed_at": "2026-10-24T10:15:00+01:00"
  }
}
FieldDescription
refund_referenceSaySwitch reference for this refund.
transaction_referenceReference of the original successful transaction.
amountAmount returned to the customer.
feeTotal refund fee.
fee_breakdown.original_transaction_feeOriginal transaction fee included in the refund cost.
fee_breakdown.configured_refund_feeConfigured refund fee.
fee_breakdown.total_feeTotal of both fee components; matches fee.
total_reservedRefund amount plus fee that was reserved.
fundingFunding state and the available/pending balance reservation split.
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.
currencyRefund currency: USD or NGN.
statusCurrent refund status: awaiting_settlement, pending, processing, success, failed, or rejected.
channelcard or bank_transfer.
processing_modemanual or automatic.
external_referenceProcessing reference when available.
requested_atISO 8601 time when the request was accepted.
completed_atISO 8601 completion time, or null before successful completion.

Refund status describes the processing lifecycle, while funding.status describes its reserved money. Only data.status: "success" confirms that the customer was refunded. An awaiting_settlement, pending, processing, or failed refund has not completed.

Do not submit another refund merely because the current refund is awaiting settlement, pending, processing, or failed. SaySwitch support handles review, requery, and safe reprocessing for failed automatic refunds. Merchants cannot manually change automatic refund statuses.

Refund Not Found

HTTP 404:

{
  "success": false,
  "message": "Refund not found."
}

If full S2S payload encryption is enabled, this GET request has no encrypted body, but the response is encrypted and must be decrypted using your existing response-decryption process.