Refunds in Sandbox

Refunds can also be initiated in the sandbox environment. Here's how:

1. Initiate a refund

To refund a pay-in transaction in the sandbox environment, simply make a request to this endpoint:

https://api.korapay.com/merchant/api/v1/refunds/initiate

The request would have the following parameters:

Parameter	Type	Required	Description
`amount`	Decimal	Optional	This is the amount of the refund. When this is passed, a partial refund is processed if this amount is less than the initial payment amount. However, when it is not passed, or the amount passed matches the payment amount, a full refund is processed.
`payment_reference`	String	Required	This is the reference of the payment to be refunded.
`reference`	String	Required	(Maximum of 50 characters) This is a unique reference for the refund that should be generated by the merchant.
`reason`	String	Optional	(Maximum of 200 characters) This is the reason for the refund.
`webhook_url`	String	Optional	(Maximum of 200 characters) The webhook to receive refund notification
`completion_status`	String	Optional	(Can either be `success` of `failed`) This specifies the simulated final status of the refund. When provided, it triggers a webhook event corresponding to the specified status.
`status_reason`	String	Optional	(Maximum of 200 characters) This provides a custom reason for the simulated `completion_status`.This mimics the status reason that would normally be returned by the system in a real refund scenario. It is included in the webhook payload.

Here's what the response could look like:

{
    "status": true,
    "message": "Refund successfully initiated",
    "data": {
        "refund_reference": "TXN-123456",
        "refund_date": "2025-04-03T08:27:22.646Z",
        "status": "processing",
        "payment_reference": "TXN-234,
        "reason": "Customer requested refund",
        "amount_returned": 120,
        "currency": "NGN"
    }
}

{
    "status": false,
    "message": "Amount can't be more than NGN 2000",
    "data": null
}

For the webhooks, here's how the response could look like at initiation:

{
   "event": "refund.success",
   "data": {
       "amount": 100,
       "status": "success",
       "status_reason": "success test transaction",
       "currency": "NGN",
       "reference": "TXN-123456",
       "payment_reference": "TXN-1",
       "created_at": "2025-07-03T06:44:59.285Z",
       "completed_at": "2025-07-03T06:44:59.342Z"
   }
}

{
  "event": "refund.failed",
  "data": {
    "amount": 100,
    "status": "failed",
    "status_reason": "failed test transaction",
    "currency": "NGN",
    "reference": "TXN-123456",
    "payment_reference": "TXN-1",
    "created_at": "2025-07-03T06:49:42.938Z",
    "completed_at": "2025-07-03T06:49:43.007Z"
  }
}