Chargebacks are raised by Kora for settled transactions. When a chargeback is raised, the merchant can decide based on their investigations, to accept, decline or partially decline the chargeback.

If a chargeback is accepted, the complete chargeback amount is debited from the merchant’s position. If the chargeback is partially declined the merchant needs to enter the amount they are willing to accept and submit evidence to back their choice. The merchant may also choose to decline the entire chargeback.

As a merchant, you are required to provide the following as evidence (if you choose to decline a chargeback):

A merchant rebuttal which explains that the customer participated in and executed the transaction and cardholder is in possession of the service/good.
The payment receipt/proof that proves that the cardholder benefited from the service.

Kindly ensure that the transaction receipts are legible enough and contain the details of the customer and transaction, such as masked PAN, customer's name, IP address, email address, transaction date and amount, etc.

🚧
If a chargeback isn't acted upon before its deadline elapses, it becomes automatically accepted.

If a merchant completely or partially declines a chargeback, Kora reserves the right, based on the evidence provided, to mark the chargeback as Lost or Won. A chargeback is marked as Won if Kora determines the evidence provided is sufficient.

Update Chargeback

Merchants can choose to accept, decline or partially decline a chargeback.

To update a chargeback, make a PATCH request to the following endpoint:
https://api.korapay.com/api/v1/chargebacks/:reference

The request body should have the following parameters:

Parameter	Type	Required?	Description
`status`	String	Required	This is the status to which you want to update the chargeback. It can be `accepted`, `declined`, or `partial`.
`evidence`	String	Optional	Required if status is either declined or partial. The value is the reference used when uploading supporting evidence. Learn more
`reason`	String	Optional	Required if status isn’t accepted. This is the explanation for why the chargeback is declined or partially declined.
`approved_amount`	Number	Optional	Required if status is partial. This is the amount approved for the chargeback.

Here's what the response to the request could look like:

{ 
	"status": true, 
	"message": "Chargeback status successfully updated", 
	"data": { 
		"reference": "KPY-CHG-X7RR9SHYQMLLY3D" 
  }
}

{
    "status": false,
    "message": "Error updating chargeback status",
    "data": null
}

Uploading Supporting Evidence

To decline or partially decline a chargeback, the merchant is required to upload evidence in PDF to support their claim. Kindly view the documentation for uploading supporting evidence here.

Don't forget to set the purpose to chargeback_supporting_document.

Get Chargeback List

Merchants can retrieve a list of chargebacks and filter them by parameters. To do this, make a GET request to the following endpoint:
https://api.korapay.com/api/v1/chargebacks.

Here are the parameters for the request:

Parameter	Type	Required	Description
`currency`	String	No	The list of chargebacks under the specified currency
`date_from`	String	No	This specifies the start date for filtering chargebacks.
`date_to`	String	No	This specifies the end date for filtering chargebacks.
`limit`	Number	No	This defines the maximum number of chargebacks records to return on a single call.
`starting_after`	String	No	This returns results starting after the provided chargebacks cursor.
`ending_before`	String	No	This returns results ending before the provided chargebacks cursor.

A successful response to the request could look like this:

{
    "status": true,
    "message": "Chargebacks retrieved successfully",
    "data": {
        "data": [
            {
                "pointer": "cus_17F",
                "account_id": 25,
                "reference": "KPY-CHG-9w905W7QY2A9jzw",
                "payment_reference": "KPY-PAY-ZKEUshaeZcC1pzLB",
                "transaction_reference": "KPY-CW-VuCAFV2JbzYS0If5",
                "batch_code": "KPY-CHG-BTCH-5U8nyzVBoEHp8fm",
                "status": "accepted",
                "currency": "NGN",
                "amount": "100.00",
                "approved_amount": "100.00",
                "deadline": "2026-01-29T22:04:00.000Z",
                "payment_method": "card",
                "reason": "testing",
                "channel": "api",
                "customer_name": "John Doe",
                "customer_email": "[email protected]",
                "created_at": "2026-01-26 17:02:13"
            }]
    }
}

Get Chargeback Details

Merchants can also get the details of a chargeback. To do this, make a GET request to the following endpoint:
https://api.korapay.com/api/v1/chargebacks/:reference.

A successful response to this request could look like this:

{
  "status": true,
	"message": "Chargeback details retrieved successfully",
  "data": {
		"pointer": "cus_17F",
		"account_id": 25,
		"reference": "KPY-CHG-9w905W7QY2A9jzw",
		"payment_reference": "KPY-PAY-ZKEUshaeZcC1pzLB",
		"transaction_reference": "KPY-CW-VuCAFV2JbzYS0If5",
		"batch_code": "KPY-CHG-BTCH-5U8nyzVBoEHp8fm",
		"status": "accepted",
		"currency": "NGN",
		"amount": "100.00",
		"approved_amount": "100.00",
		"deadline": "2026-01-29T22:04:00.000Z",
		"payment_method": "card",
		"reason": "testing",
		"channel": "api",
		"customer_name": "John Doe",
		"customer_email": "[email protected]",
    "created_at": "2026-01-26 17:02:13"
	}
}

Testing Chargebacks in Sandbox

In order to test chargeback, we’ve provided two endpoints on the sandbox environment that helps simulate the initiation and completion steps of the chargeback flow.

🚧
Please note that these endpoints are only available in the sandbox environment.

Initiate Chargeback

This allows a merchant to simulate the initiate a chargeback just as Kora would initiate a real chargeback. To do this, make a POST request to the following endpoint:
https://api.korapay.com/api/v1/chargebacks/initiate.

The request should have the following parameters:

Parameter	Type	Required	Description
`reference`	String	Required	This is the reference of the transaction.
`amount`	Number	Required	This is the amount to be raised as chargeback.
`reason`	String	Required	This is the reason why the chargeback was raised.
`deadline`	DateString	Required	This is the deadline for a merchant to treat the chargeback, after which the chargeback will be automatically accepted. It should be in the format: `YYYY-MM-DDTHH:mm:ss`

A successful response to the request could look like this:

{
  "status": true,
	"message": "Chargeback initiated successfully", 
	"data": { 
			"reference": "KPY-CHG-X7RR9SHYQMLLY3D" 
	}
}

Complete Chargeback

This allows a merchant mark a declined or partially declined transaction as Lost, Won or Partial. To do this, simply make a PATCH request to the following endpoint:
https://api.korapay.com/api/v1/chargebacks/:reference

Here are the parameters for this request:

Parameters	Type	Required	Description
`status`	String	Required	This is the status of the chargeback. It can either be `lost`, `won`, or `partial`.
`approved_amount`	Number	Optional	Required when status is partial. This is the amount for the chargeback.

Parameters

Type

Required

Description

status

String

Required

This is the status of the chargeback. It can either be lost, won, or partial.

approved_amount

Number

Optional

Required when status is partial.

This is the amount for the chargeback.

An example of the response to this request could look like this:

{ 
	"status": true, 
	"message": "Chargeback status successfully Updated", 
	"data": { 
			"reference": "KPY-CHG-X7RR9SHYQMLLY3D" 
	}
}

{
    "status": false,
    "message": "Error updating chargeback status",
    "data": null
}

Webhooks

We send webhooks when a chargeback is created and when it is marked as won, lost or partial. Here's an example of the webhooks payload:

{
  "event": "chargeback.pending",
  "data": {
    "status": "pending",
    "payment": {
      "status": "success",
      "reference": "KPY-CM-bGYRoeXuQd9G25x",
      "created_at": "2025-10-28T22:06:20.000Z",
      "amount_paid": 2865.62,
      "amount_accepted": 3000
    },
    "currency": "NGN",
    "deadline": "2026-01-12T19:00:00.000Z",
    "reference": "KPY-CHG-xYvpQYHw7wYIfzs",
    "created_at": "2026-01-12T14:55:08.000Z",
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "payment_method": "card",
    "accepted_amount": 0,
    "chargeback_amount": 300,
    "chargeback_reason": "test test"
  }
}