Refund

Initiate a refund for a previously completed transaction. Refunds are processed asynchronously — the response confirms the refund has been queued, and a webhook notification is sent once the funds are returned to the customer.

How Refunds Work

Vesicash refunds are sent directly to the customer's mobile money wallet using the payment reference from the original transaction. Once queued, you can track the refund status via the status endpoint or listen for the webhook event.

Amount Constraint

The refund amount must not exceed the original transaction amount. Partial refunds are supported — you may call this endpoint multiple times as long as the cumulative refunded amount does not exceed the original charge.

POST: /v1/payment/refunds/process

Headers

Name	Type	Description
secret-key	string	Your Vesicash secret key
public-key	string	Your Vesicash public key

Request body

• amount (number): The amount to be refunded. This value must not be greater than the amount associated with the specified payment reference.

• payment_reference (string): The reference of the payment that needs to be refunded. This should match the original payment reference.

• country_id (string): The unique identifier for the country in which the transaction is being processed. To retrieve a valid country_id, call the Get Countries endpoint and use the country_id field from the matching country object in the response.

• transfer_to (string): The destination type for the refund disbursement. Currently supports mobile_number.

• momo_phone_number (string): The mobile money phone number to receive the refund. Must be in E.164 format. eg. 233211111111

• reason (string): The reason for the refund.

Request

For example, you can make a post request to the endpoint above and pass in the raw json data below to refund a successful transaction.

{
    "amount":1,
    "country_id":"{{ghana_country_id}}",
    "transfer_to":"mobile_number",
    "momo_phone_number": "{{phone_number}}",
    "payment_reference":"{{reference}}",
    "webhook_url": "{{webhook_url}}",
    "reason":"testing refund reason" //optional
}

Response

{
    "status": "success",
    "code": 200,
    "message": "refund queued successfully",
    "data": {
        "status": "pending",
        "message": "refund queued successfully",
        "reference": ""
    }
}