Refunds

Overview

The Refunds API lets merchants initiate refunds for completed transactions. It’s often used when a customer cancels an order, reports a double charge, or qualifies for a promotional refund

Endpoint

POST {baseUrl}/api/v1/Refunds/InitiateRefund Initiates a refund request.

Authentication

Use a Bearer token via the Authorization header.

Request Body

JSON
{
  "transactionReference": "SSP6387756GL02507RDF56CBE",
  "amount": 5000,
  "reason": "Customer canceled order",
  "explainMore": "Add detailed description here"
}

Response Example

JSON
{
    "data": true,
    "httpStatusCode": 200,
    "hasError": false,
    "responseMessage": {
        "title": "Successful"
    },
    "responseCode": 0
}

Curl Sample

curl -X 'POST' \
  '{baseUrl}/api/v1/Refunds/InitiateRefund' \
  -H 'accept: text/plain' \
  -H 'DeviceType: test' \
  -H 'ApplicationID: 1' \
  -H 'SecretKey: test' \
  -H 'Authorization: bearer gl0bGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
  -H 'Content-Type: application/json' \
  -d '{
  "transactionReference": "SSP6387756GL02507RDF56CBE",
  "amount": 5000,
  "reason": "Customer canceled order",
  "explianMore": "Add detailed description here"
}'

Refund Status API Allows querying the status of a previously initiated refund.

Sample Request Replace {refund_id} with your actual refund identifier. GET {baseUrl}/api/v1/Refunds/GetRefund?transactionNumber={refund_id}

Response Example

JSON
{
    "data": {
        "id": 2,
        "transactionReference": "SSP6387756GL02507RDF56CBE",
        "providerRefundId": "737356",
        "amount": 5000.00,
        "refundType": "overpay",
        "reason": "test refund",
        "status": "Pending",
        "createdAt": "2025-07-22T10:27:49",
        "createdBy": "[email protected]",
        "explainMore": "No reason"
    },
    "httpStatusCode": 200,
    "hasError": false,
    "responseMessage": {
        "title": "record retrieved successfully."
    },
    "responseCode": 61
}

curl -X 'GET' \
  '{baseUrl}/api/v1/Refunds/GetRefund?transactionNumber=7373655' \
  -H 'accept: */*' \
  -H 'DeviceType: 1' \
  -H 'ApplicationID: test' \
  -H 'SecretKey: test' \
  -H 'Authorization: bearer gl0JhbGciOiJIUzI1NiIsInRGhfRI6IkpXVCJ9'

GET All Refunds Sample Request : {baseUrl}/api/v1/Refunds/GetAllRefunds

JSON
{
    "data": {
        "data": [
            {
                "id": 3,
                "transactionReference": "SSP6387756GL02507RDF56CBE",
                "providerRefundId": "8372664",
                "amount": 5000.00,
                "refundType": "overpay",
                "reason": "test refund",
                "status": "Pending",
                "createdAt": "2025-07-22T10:31:23",
                "createdBy": "[email protected]",
                "explainMore": "No reason"
            }
        ],
        "totalCount": 1,
        "pageNumber": 1,
        "pageSize": 10,
        "totalPages": 1
    },
    "httpStatusCode": 200,
    "hasError": false,
    "responseMessage": {
        "title": "Refund records retrieved successfully."
    }
}

Suggested Usage

• Use Refunds for amicable resolutions.

• Use Chargebacks when a refund is not possible or there’s a customer dispute requiring formal review.