Get Refunds
Retrieve a paginated list of your USD card and standard NGN bank-transfer refunds for the authenticated test or live environment.
See the Refund Overview for funding, fees, and status lifecycle guidance.
Endpoint
GET https://backendapi.sayswitchgroup.com/api/v1/refundRequest Examples
curl --request GET \
--url "https://backendapi.sayswitchgroup.com/api/v1/refund?page=1" \
--header "Authorization: Bearer YOUR_SECRET_KEY" \
--header "Accept: application/json"Keep your secret key and this request on your server.
Response
{
"success": true,
"message": "Refunds retrieved.",
"data": {
"current_page": 1,
"data": [
{
"refund_reference": "REF_USD_2026_001",
"transaction_reference": "USD_TXN_2026_001",
"amount": "25.00",
"fee": "1.00",
"fee_breakdown": {
"original_transaction_fee": "0.00",
"configured_refund_fee": "1.00",
"total_fee": "1.00"
},
"total_reserved": "26.00",
"funding": {
"status": "funded",
"available_reserved": "26.00",
"pending_reserved": "0.00",
"pending_funded_amount": "0.00",
"pending_remaining": "0.00",
"funded_at": "2026-10-24T10:00:00+01:00"
},
"currency": "USD",
"status": "pending",
"channel": "card",
"processing_mode": "manual",
"external_reference": null,
"requested_at": "2026-10-24T10:00:00+01:00",
"completed_at": null
},
{
"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": "funded",
"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": "processing",
"channel": "bank_transfer",
"processing_mode": "automatic",
"external_reference": null,
"requested_at": "2026-10-24T10:05:00+01:00",
"completed_at": null
}
],
"first_page_url": "https://backendapi.sayswitchgroup.com/api/v1/refund?page=1",
"from": 1,
"last_page": 1,
"last_page_url": "https://backendapi.sayswitchgroup.com/api/v1/refund?page=1",
"next_page_url": null,
"path": "https://backendapi.sayswitchgroup.com/api/v1/refund",
"per_page": 20,
"prev_page_url": null,
"to": 2,
"total": 2
}
}The newest refunds are returned first, with 20 records per page. Use the page query parameter or the pagination URLs to retrieve more records.
Refund Fields
| Field | Type | Description |
|---|---|---|
refund_reference | string | SaySwitch reference for the refund. |
transaction_reference | string | Reference of the original successful transaction. |
amount | string | Amount being returned to the customer. |
fee | string | Total refund fee. |
fee_breakdown.original_transaction_fee | string | Original transaction fee included in the refund cost. |
fee_breakdown.configured_refund_fee | string | Configured refund fee. |
fee_breakdown.total_fee | string | Total of both fee components; matches fee. |
total_reserved | string | Refund amount plus fee reserved from the wallet. |
funding.status | string | awaiting_settlement, funded, consumed, or released. |
funding.available_reserved | string | Amount reserved from available balance. |
funding.pending_reserved | string | Amount reserved from eligible pending balance. |
funding.pending_funded_amount | string | Pending reservation already funded through settlement. |
funding.pending_remaining | string | Pending reservation still awaiting settlement. |
funding.funded_at | string or null | Time the refund became fully funded. |
currency | string | USD or NGN. |
status | string | awaiting_settlement, pending, processing, success, failed, or rejected. |
channel | string | card or bank_transfer. |
processing_mode | string | manual or automatic. |
external_reference | string or null | Processing reference when available. |
requested_at | string or null | ISO 8601 time when the request was accepted. |
completed_at | string or null | ISO 8601 time when the refund completed successfully. |
For one refund, use Get Refund Details.
Refund status tracks processing, while funding.status tracks the reserved money. See Funding Object for all funding fields.
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.