RefundsInitiate Refunds

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

Headers

Content-Type: application/json
Authorization: Bearer YOUR_SECRET_KEY
Idempotency-Key: UNIQUE_REFUND_REQUEST_KEY

Use 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"
}
FieldTypeRequiredDescription
transaction_referencestringConditionalOriginal successful transaction reference. Required unless reference is supplied.
referencestringConditionalAlternative name for transaction_reference.
amountnumeric string or numberNoUSD 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_notestringNoMerchant description, up to 2,000 characters.
idempotency_keystringNoBody 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.