Chargebacks

Overview

The Chargebacks API handles disputed transactions. It’s commonly used when a customer claims a charge was unauthorized or fraudulent, or if a refund was declined and a formal dispute is necessary.

Endpoint

When a chargeback occurs, merchants must:

Use POST {baseUrl}/api/v1/Chargeback/AcceptChargeBack to accept

JSON
{
  "txRef": "CHG53827867342",
  "note": "I accept that the value was not delivered to the customer."
}

curl -X 'POST' \
  '{baseUrl}/api/v1/Chargeback/AcceptChargeBack' \
  -H 'accept: text/plain' \
  -H 'DeviceType: 1' \
  -H 'ApplicationID: 3qfw3' \
  -H 'SecretKey: afwqefdqfe' \
  -H 'Authorization: bearer gl0JhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
  -H 'Content-Type: application/json' \
  -d 'JSON
{
  "txRef": "CHG53827867342",
  "note": "I accept that the value was not delivered to the customer."
}'

For disputes: Attach evidence (proof of delivery, receipts, or communications) via multipart/form-data POST {baseUrl}/api/v1/Chargeback/DeclineChargeBack?TxRef=SSP637544_INV01&Note=enter note

curl -X 'POST' \
  '{baseUrl}/api/v1/Chargeback/DeclineChargeBack?TxRef=CHhgajweik&Note=The%20customer%20recieved%20his%20funds' \
  -H 'accept: text/plain' \
  -H 'DeviceType: 1' \
  -H 'ApplicationID: sfvfwefwf' \
  -H 'SecretKey: wef3f3tg42gh24' \
  -H 'Authorization: bearer gl0JhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
  -H 'Content-Type: multipart/form-data' \
  -F 'File=@Screenshot_evidence.png;type=image/png'

Track status via GET {baseUrl}/api/v1/Chargeback/GetChargeBackDispute?disputeId={id} Automated webhooks notify on new chargebacks and status changes.

JSON
{
    "data": {
        "id": 0,
        "txRef": "",
        "disputeType": 0,
        "amount": 0,
        "currency": "",
        "agentName": "",
        "agentId": 0,
        "deadline": "0001-01-01T00:00:00",
        "isExceededDeadline": false,
        "status": "",
        "agentReply": "",
        "note": "",
        "responderId": null,
        "responderName": null,
        "dateInitiated": "0001-01-01T00:00:00",
        "dateDisputed": null
    },
    "httpStatusCode": 200,
    "hasError": false,
    "responseMessage": {
        "title": "records retrieved successfully.",
        "actionMessage": ""
    },
    "responseCode": 61
}

curl -X 'GET' \
  '{baseUrl}/api/v1/Chargeback/GetChargeBackDispute?disputeId=3' \
  -H 'accept: text/plain' \
  -H 'DeviceType: 1' \
  -H 'ApplicationID: adas' \
  -H 'SecretKey: afaf'

GET All : {baseUrl}/api/v1/Chargeback/GetAllChargeBackDispute?StartDate=01-01-2025&EndDate=12-12-2025&PageNumber=1&PageSize=20

curl -X 'GET' \
  '{baseUrl}/api/v1/Chargeback/GetAllChargeBackDispute?StartDate=2025-01-12&EndDate=2025-08-11&PageNumber=1&PageSize=20' \
  -H 'accept: text/plain' \
  -H 'DeviceType: 1' \
  -H 'ApplicationID: dfgbfg' \
  -H 'SecretKey: wfg3t34tr34t' \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9'

Example Response

JSON
{
    "data": {
        "responseCode": "00",
        "responseMessage": "Operation successful.",
        "data": {
            "records": [
                {
                    "id": 3,
                    "txRef": "SSPPL638835857091361855162c",
                    "disputeType": 1,
                    "amount": 9992.31,
                    "currency": "NGN",
                    "agentName": "Favvyx Kaddiex",
                    "agentId": 758,
                    "deadline": "2025-06-26T13:53:21",
                    "isExceededDeadline": true,
                    "status": "Pending",
                    "agentReply": "",
                    "note": "The Merchant’s proof of denying the claim has been accepted; hence, the customer will not be refunded.",
                    "responderId": null,
                    "responderName": null,
                    "dateInitiated": "2025-06-24T13:53:21",
                    "dateDisputed": null
                }
            ],
            "totalRecords": 1,
            "pageSize": 20,
            "pageNumber": 1,
            "totalPages": 1,
            "returnedRecords": 1
        },
        "totalRecords": 1
    },
    "httpStatusCode": 200,
    "hasError": false,
    "responseMessage": {
        "title": "records retrieved successfully.",
        "actionMessage": ""
    },
    "responseCode": 61
}

Purpose

Facilitates the process for users or merchants to dispute unauthorized or problematic transactions and formally initiate a chargeback claim. Typically used when:

• A refund is denied

• A customer suspects fraud

• Services were not delivered