Refund - Novasend API

API Direct Refund

 
       POST https://business.novasend.app/v1/payin/{reference}/refund

This endpoint allows you to partially or fully refund a previously completed customer payment (Payin). The refund either credits the customer’s account or cancels the transaction depending on the original payment method.

Refund rules:

Payout (Transfer): In case of a failed payment status, Novasend refunds the gross amount (Charged amount + fees) to the Merchant's wallet

Payin (Payment): In case of a failed payment status where the Merchant's customer has been debited, Novasend verifies with its partners the transaction status. When it is confirmed that the funds have been collected by the partner, Novasend changes the transaction status from failed to success with a callback (webhook) notification, and credits the Merchant's account within a maximum of 48 hours.

Conditions

The payment transaction must have a success status.
The transaction must not have been previously refunded.

Request Headers

Header	Description	Required
Authorization	Used to authenticate the API, `Basic base64(api_key:api_client)`	✅
X-Idempotency-Key	Ensures transaction uniqueness. The value must be a UUID	✅
Content-Type	`application/json`
Accept-Language	Language used for error messages. Supported values: `en`, `fr`

Request

Champ	Type	Description	Obligatoire
`reason`	`string`	La raison du remboursement.	✅
`externalReference`	`string`	La référence envoyé par l'API.	✅

 {
   "reason": "Client cancellation",
   "externalReference": "refund_9843b-9911c-qa87"
 }

Response

  {
    "type": "refund",
    "reference": "rf_fhchi842jyimwiugjgszcxvb8n",
    "originalReference": "tr_fhchi842jyimwiugjgszcxvb8n",
    "amount": 150,
    "fee": 0,
    "currency": "XOF",
    "status": "processing",
    "reason": "Client cancellation",
    "refundType": "partial",
    "customerMsisdn": "+2250702968786",
    "customerName": "John",
    "createdAt": "2025-08-23T12:34:48.189Z",
    "transaction": {
      "reference": "tr_rf84dhf9pqiuhd38",
      "status": "pending",
      "processedAt": null
    }
  }

Response Fields Description

Field	Description
type	Type of operation (`refund`).
reference	Unique refund identifier.
originalReference	Reference of the original payment to be refunded.
amount	Amount to be refunded.
fee	Associated fees (if applicable).
currency	Refund currency (`XOF`, `USD`, etc.).
status	Refund status (`pending`, `processing`, `completed`, `failed`).
reason	Refund reason provided by the merchant.
refundType	Refund type (`full` or `partial`).
customerMsisdn	Refunded customer phone number.
customerName	Customer name.
createdAt	Timestamp when the refund request was created.
transaction	Refund transaction details on the Core System side.

Transfer Errors