Refund Payment
Reverses a settled customer payment back to the originating 13-digit account.
POST/v1/c2b/refundLive & Sandbox
Request Headers
| Header | Type | Status | Description |
|---|---|---|---|
Authorization | string | Required | Bearer token obtained via POST /v1/oauth2/token. |
Content-Type | string | Required | application/json |
Idempotency-Key | string | Recommended | Unique key for this operation, 8–80 characters. Send it to make retries safe: repeating the same key returns the original result instead of performing the operation twice. Without it the API derives a key from the request body and replays the original result for a few minutes, so an accidental double submit is still ignored. |
Body Parameters (JSON)
| Parameter | Type | Status | Description |
|---|---|---|---|
transactionId | string | Required | Identifier of the settled transaction to refund (e.g. TXN_C2B_84920199). |
amount | number | Required | Amount in base currency to reverse back to customer. Must be less than or equal to original transaction value. |
reason | string | Optional | Explanation for the refund (e.g. Customer cancellation). |
Request Code Snippets (cURL, Node, Python, PHP, Go)
Request Example
curl -X POST https://developer.vixzz.com/v1/c2b/refund \
-H "Authorization: Bearer vxz_tok_c2b_8f9k3m9s2a1l" \
-H "Content-Type: application/json" \
-d '{
"transactionId": "TXN_C2B_84920199",
"amount": 2500,
"reason": "customer_cancellation"
}'JSON Return Response Body (200 OK)
Response
{
"success": true,
"refundId": "REF_9M4Z8819",
"transactionId": "TXN_C2B_84920199",
"amount": 2500,
"currency": "KES",
"status": "REFUNDED",
"refundedAt": "2026-09-07T02:30:00.000Z"
}