Refund

The refund endpoint enables merchants to initiate refunds (Full and Partial) for previously processed transactions via a PUT request. It requires the original transaction reference and processes the specified refund amount using either the Nectar-generated or merchant reference.

Note: When initiating a refund for a transaction, there are two possible results:

Refunded – The refund is successfully processed and approved.
Declined – The refund request is rejected due to insufficient funds, invalid transaction reference, expired authorization, or other restrictions.

Endpoint

PUT /transaction/refund/{{transactionReference}}

Headers

Key	Value	Required	Description
`Content-Type`	`application/json`	Yes	Specifies JSON payload format.
`Authorization`	`{{private_key}}`	Yes	Merchant's private key for authentication.

Request Parameters

Path Parameter

Parameter	Type	Description
`transactionReference`	`string`	Unique reference of the original transaction to refund.

Authorization: Bearer {{private_key}}
Content-Type: application/json

Request Body

{
  "transactionReference": "Fa5JliRhi6vblnEHY",
  "refundAmount": 37.00,
  "refundReason": "Customer requested refund"
}

Sample Response

{
    "status": 200,
    "message": "Request successfully processed",
    "data": {
        "transactionReference": "Fa5JliRhi6vblnEHY",
        "reference": "TX187-BC6C-D61DC0D083FF",
        "refundedAmount": 37.00,
        "transactionAmount": 50.00,
        "transactionDate": "2025-05-14T18:21:20.728393",
        "refundedDate": "2025-06-14T21:43:59.502652783",
        "currencyCode": "USD",
        "status": 6,
        "acquirerCode": "00",
        "acquirerMessage": "Approved",
        "remainingAmount": 13.00,
        "refundHistory": [
            {
                "refundId": "AVT84h9nRMIgR_RF",
                "amount": 37.00,
                "timestamp": "2025-06-14T21:43:58.866706",
                "status": "REFUNDED"
            }
        ],
        "partialRefund": true // Partial if refundedAmount less than transactionAmount
    },
    "errors": []
}

Response Fields

Field	Type	Description
`transactionReference`	`string`	Unique reference for the refund transaction.
`reference`	`string`	Merchant’s original order reference.
`refundedAmount`	`decimal`	Refunded transaction amount.
`transactionAmount`	`decimal`	Original transaction amount..
`transactionDate`	`string`	Timestamp when the transaction was processed.
`refundedDate`	string	Timestamp when the refund was processed.
`currencyCode`	`string`	Currency code (e.g., `NGN/ USD`).
`status`	`integer`	Refund status code (see Status Codes).
`acquirerCode`	`string`	Acquirer/bank response code (00 = approved).
`acquirerMessage`	`string`	Acquirer/bank status message (e.g., `Approved`).

Error Handling

400 Bad Request: Invalid transactionReference or missing parameters.
401 Unauthorized: Invalid private_key.
404 Not Found: Original transaction not found.
500 Server Error: Gateway processing failure.