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"
}
}| Field | Description |
|---|---|
refund_reference | SaySwitch reference for this refund. |
transaction_reference | Reference of the original successful transaction. |
amount | Amount returned to the customer. |
fee | Total refund fee. |
fee_breakdown.original_transaction_fee | Original transaction fee included in the refund cost. |
fee_breakdown.configured_refund_fee | Configured refund fee. |
fee_breakdown.total_fee | Total of both fee components; matches fee. |
total_reserved | Refund amount plus fee that was reserved. |
funding | Funding state and the available/pending balance reservation split. |
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. |
currency | Refund currency: USD or NGN. |
status | Current refund status: awaiting_settlement, pending, processing, success, failed, or rejected. |
channel | card or bank_transfer. |
processing_mode | manual or automatic. |
external_reference | Processing reference when available. |
requested_at | ISO 8601 time when the request was accepted. |
completed_at | ISO 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.