RefundsGet Refunds

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/refund

Request 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

FieldTypeDescription
refund_referencestringSaySwitch reference for the refund.
transaction_referencestringReference of the original successful transaction.
amountstringAmount being returned to the customer.
feestringTotal refund fee.
fee_breakdown.original_transaction_feestringOriginal transaction fee included in the refund cost.
fee_breakdown.configured_refund_feestringConfigured refund fee.
fee_breakdown.total_feestringTotal of both fee components; matches fee.
total_reservedstringRefund amount plus fee reserved from the wallet.
funding.statusstringawaiting_settlement, funded, consumed, or released.
funding.available_reservedstringAmount reserved from available balance.
funding.pending_reservedstringAmount reserved from eligible pending balance.
funding.pending_funded_amountstringPending reservation already funded through settlement.
funding.pending_remainingstringPending reservation still awaiting settlement.
funding.funded_atstring or nullTime the refund became fully funded.
currencystringUSD or NGN.
statusstringawaiting_settlement, pending, processing, success, failed, or rejected.
channelstringcard or bank_transfer.
processing_modestringmanual or automatic.
external_referencestring or nullProcessing reference when available.
requested_atstring or nullISO 8601 time when the request was accepted.
completed_atstring or nullISO 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.