Refund

The POST /v1/payin/{reference}/refund endpoint allows you to partially or fully refund a previously validated customer payment (Payin).

This operation credits the customer's account or cancels the transaction depending on the initial settlement method.

Endpoint

Element	Description
Method	`POST`
URL	`/v1/payin/{reference}/refund`
Auth	✅ `Authorization: Basic base64(api_key:api_client)`
Idempotence	✅ `X-Idempotency-Key` required
Payload Type	`application/json`

Purpose

Perform a full refund of a validated payment.
Perform a partial refund if the refunded amount is less than the original payment.
Restore consistency between customer transactions and merchant balances.
Automate dispute and cancellation management.

Request Example

POST /v1/payin/tr_fhchi842jyimwiugjgszcxvb8n/refund

Headers

Key	Description	Required
`Authorization`	Basic base64(api_key:api_client)	✅
`X-Idempotency-Key`	UUID ensuring request uniqueness	✅

Request Body

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

Response Example

{
  "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
  }
}

Field Interpretation

Field	Description
type	Operation type (`refund`).
reference	Unique refund identifier.
originalReference	Reference of the original payment to refund.
amount	Amount to refund.
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	Phone number of the refunded customer.
customerName	Customer's name.
createdAt	Refund request creation timestamp.
transaction	Refund transaction details on the Core System side.

Refund Statuses

Status	Description
pending	Request received, awaiting processing.
processing	Refund in progress.
completed	Refund validated and credited to customer.
failed	Refund refused or rejected (insufficient funds, deadline exceeded, etc.).
reversed	Amount returned to merchant after failure or manual cancellation.

Difference Between Full and Partial Refund

Type	Description	Condition
Full (`full`)	Complete refund of the initial amount.	`amount` = original payment amount
Partial (`partial`)	Refund of part of the initial amount.	`amount` < original payment amount

💡 A payment can be partially refunded multiple times, as long as the total refunded amounts ≤ initial amount.

Refund Verification

Once the refund is initiated, its status can be tracked via:

GET /v1/payin/{reference}

or via webhooks:

Event	Description
`refund.processing`	Refund in progress.
`refund.completed`	Refund executed successfully.
`refund.failed`	Refund refused.

Constraints and obligation

Rule	Description
Unique refund per reference	Each refund generates a new reference (`rf_...`).
Maximum amount	Cannot exceed the original transaction amount.
Time window	A refund can only be requested during the authorized period (e.g., 7 days after payment).
Available funds	The merchant must have sufficient balance to cover the refund.
Security	HMAC signature verification and refund logging

Possible Errors

Code	Message	Probable Cause	Recommended Action
400	Invalid amount	Amount greater than original payment	Verify the amount
401	Unauthorized	Invalid authentication	Verify API key
403	Refund not allowed	Non-refundable transaction	Check refund conditions
404	Payment not found	Reference not found	Verify original reference
409	Duplicate refund	Refund already attempted	Use a different idempotency key
500	Internal Server Error	Server error	Retry later

Common Use Cases

Case	Example	Description
Customer cancellation	`reason: "Client cancellation"`	User cancels their order after payment.
Partial refund	`amount: 500`	Merchant partially refunds a purchase.
Billing error	`reason: "Duplicate charge"`	Duplicate payment to refund.

Transaction Types

Type	Customer Confirmation	Mobile Money Interaction	Notification
Triggered payment	✅ Yes	❌ No	✅ Yes
Internal transfer (P2P)	❌ No	❌ No	✅ Yes

Balance API Keys