Initiate a Refund
Use this endpoint to request a manual USD card refund or an automatic full refund for a standard NGN bank-transfer transaction.
An accepted request reserves funds and returns HTTP
202. It does not mean that the refund has been completed. Verify the final status or wait for a refund webhook before treating the refund as successful.
Read the Refund Overview first for supported transactions, fees, wallet funding, statuses, and the complete integration flow.
Refund fees are based on your merchant agreement. Fees in the examples are illustrative; use the returned fee_breakdown and total_reserved for each refund.
Endpoint
POST https://backendapi.sayswitchgroup.com/api/v1/refundHeaders
Content-Type: application/json
Authorization: Bearer YOUR_SECRET_KEY
Idempotency-Key: UNIQUE_REFUND_REQUEST_KEYUse the test or live secret key that matches the original transaction. Idempotency-Key is strongly recommended for every refund request. If both the header and idempotency_key body field are supplied, the header takes precedence.
Request Body
{
"transaction_reference": "SSW_TRANSACTION_REFERENCE",
"amount": "25.00",
"merchant_note": "Customer requested a partial refund"
}| Field | Type | Required | Description |
|---|---|---|---|
transaction_reference | string | Conditional | Original successful transaction reference. Required unless reference is supplied. |
reference | string | Conditional | Alternative name for transaction_reference. |
amount | numeric string or number | No | USD card refunds only. Supply it for a partial USD refund and omit it for a full refund. Always omit it for NGN bank-transfer refunds. |
merchant_note | string | No | Merchant description, up to 2,000 characters. |
idempotency_key | string | No | Body alternative to the Idempotency-Key header, up to 190 characters. |
Do not include callbackUrl in a refund request. Refund status notifications are delivered to your configured webhook URL.
Full USD Card Refund
Omit amount to refund the USD card transaction’s entire remaining refundable amount.
curl --request POST \
--url https://backendapi.sayswitchgroup.com/api/v1/refund \
--header "Authorization: Bearer YOUR_SECRET_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: refund-full-unique-key" \
--data '{
"transaction_reference": "SSW_TRANSACTION_REFERENCE",
"merchant_note": "Customer requested a full refund"
}'Keep your secret key on your server. Do not run this request in frontend JavaScript.
Partial USD Card Refund
Include amount to refund part of the USD card transaction’s remaining refundable amount.
curl --request POST \
--url https://backendapi.sayswitchgroup.com/api/v1/refund \
--header "Authorization: Bearer YOUR_SECRET_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: refund-partial-unique-key" \
--data '{
"transaction_reference": "SSW_TRANSACTION_REFERENCE",
"amount": "25.00",
"merchant_note": "Customer requested a partial refund"
}'Full NGN Bank-Transfer Refund
Omit amount completely. SaySwitch calculates the refundable principal from the actual amount received, subtracting any excess-payment refund that already completed successfully.
The refund is returned automatically to the verified originating bank account. Dedicated-account credits are excluded, and the merchant cannot select or modify the destination. Merchants cannot manually requery, reprocess, or change the status of an automatic refund.
curl --request POST \
--url https://backendapi.sayswitchgroup.com/api/v1/refund \
--header "Authorization: Bearer YOUR_SECRET_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: refund-ngn-unique-key" \
--data '{
"transaction_reference": "SSW_TRANSACTION_REFERENCE",
"merchant_note": "Customer requested a refund"
}'Keep your secret key on your server. Do not run this request in frontend JavaScript.
Accepted Responses
Newly accepted refunds return HTTP 202. Select a flow to see the complete common refund object.
{
"success": true,
"message": "Refund submitted and awaiting settlement funding.",
"data": {
"refund_reference": "REF_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": "awaiting_settlement",
"available_reserved": "10.00",
"pending_reserved": "16.00",
"pending_funded_amount": "0.00",
"pending_remaining": "16.00",
"funded_at": null
},
"currency": "USD",
"status": "awaiting_settlement",
"channel": "card",
"processing_mode": "manual",
"external_reference": null,
"requested_at": "2026-10-24T10:00:00+01:00",
"completed_at": null
}
}An awaiting_settlement refund is accepted but not ready for processing. Do not resubmit it. SaySwitch automatically continues after the reservation is completely funded.
See Common Refund Object and Funding Object for field descriptions.
Idempotent Retry
Send the same Idempotency-Key when retrying a request after a timeout or uncertain response. The API returns the original refund and does not reserve the wallet twice.
curl --request POST \
--url https://backendapi.sayswitchgroup.com/api/v1/refund \
--header "Authorization: Bearer YOUR_SECRET_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: refund-partial-unique-key" \
--data '{
"transaction_reference": "SSW_TRANSACTION_REFERENCE",
"amount": "25.00",
"merchant_note": "Customer requested a partial refund"
}'An idempotent retry returns HTTP 200:
{
"success": true,
"message": "Refund request already received.",
"data": {
"refund_reference": "REFUND_REFERENCE",
"transaction_reference": "SSW_TRANSACTION_REFERENCE",
"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-09-28T10:00:00+01:00"
},
"currency": "USD",
"status": "pending",
"channel": "card",
"processing_mode": "manual",
"external_reference": null,
"requested_at": "2026-09-27T12:00:00+01:00",
"completed_at": null
}
}Track a Refund
Use GET /api/v1/refund to retrieve your refunds. Use GET /api/v1/refund/status/{refund_reference} to verify one refund, and listen for refund webhooks. Both endpoints return refunds for the authenticated test or live environment only.
Do not assume that HTTP 202 means success. The Refund Overview explains the complete status and settlement lifecycle.
Validation and Eligibility Errors
Transaction Not Found
HTTP 404:
{
"success": false,
"message": "Transaction not found."
}Transaction Is Not Successful
HTTP 422:
{
"success": false,
"message": "Only successful transactions can be refunded."
}Unsupported NGN Transaction or Channel
HTTP 422:
{
"success": false,
"message": "Only standard NGN bank-transfer collections can be refunded automatically."
}Dedicated-account credits are not standard bank-transfer collections and are not eligible for this flow.
Verified Source Account Unavailable
HTTP 422:
{
"success": false,
"message": "The verified source bank account for this transaction could not be resolved."
}The refund destination cannot be supplied or changed in the request.
Amount Supplied for an NGN Refund
HTTP 422:
{
"success": false,
"message": "NGN bank-transfer transactions support full refunds only. Omit the amount field."
}Amount Exceeds the Remaining Refundable Amount
HTTP 422:
{
"success": false,
"message": "Refund amount exceeds the remaining refundable amount."
}Insufficient Eligible Funds
HTTP 422:
{
"success": false,
"message": "Insufficient funds to cover the refund amount and fee.",
"required": "101.00",
"available_balance": "20.00",
"pending_balance": "50.00",
"shortfall": "31.00",
"currency": "USD"
}pending_balance is the eligible pending balance after existing refund holds, not necessarily the gross pending balance. If available balance plus eligible pending balance cannot cover the refund and fee, the request is rejected and no funds are deducted or reserved.
Transaction Already Fully Refunded
HTTP 409:
{
"success": false,
"message": "This transaction has already been fully refunded."
}Existing Automatic Full Reversal
HTTP 409:
{
"success": false,
"message": "This payment already has an automatic full-reversal workflow."
}Unresolved Excess-Payment Refund
HTTP 409:
{
"success": false,
"message": "The automatic excess-payment refund must be resolved before a full refund can be requested."
}Invalid Request Fields
HTTP 422:
{
"success": false,
"message": "Invalid refund request.",
"errors": {
"transaction_reference": [
"The transaction reference field is required when reference is not present."
]
}
}Encrypted S2S Merchants
Merchants without full payload encryption send the normal JSON request shown above. If S2S payload encryption is enabled for your account, encrypt the complete inner refund payload using your existing SaySwitch encryption flow.
The decrypted inner payload can contain:
{
"transaction_reference": "SSW_TRANSACTION_REFERENCE",
"amount": "25.00",
"merchant_note": "Customer requested a partial refund",
"idempotency_key": "refund-encrypted-unique-key"
}For an NGN bank-transfer refund, omit amount from the decrypted inner payload as well.
Send the encrypted value in the outer request body:
{
"data": "ENCRYPTED_PAYLOAD"
}Encrypted merchants receive an encrypted response and must decrypt it using their existing response-decryption process. The refund GET endpoints do not require an encrypted request body, but their responses remain encrypted when encryption is enabled.
Encrypted Request Examples
curl --request POST \
--url https://backendapi.sayswitchgroup.com/api/v1/refund \
--header "Authorization: Bearer YOUR_SECRET_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: refund-encrypted-unique-key" \
--data '{
"data": "ENCRYPTED_PAYLOAD"
}'The encryption helper names above represent your existing implementation. Follow API Payload Encryption for the configured encryption and response-decryption process.
Never include raw card numbers, CVVs, PINs, or other card information in a refund request.