Refund Payment

Reverses a settled customer payment back to the originating 13-digit account.

POST/v1/c2b/refundLive & Sandbox

Request Headers

HeaderTypeStatusDescription
AuthorizationstringRequiredBearer token obtained via POST /v1/oauth2/token.
Content-TypestringRequiredapplication/json
Idempotency-KeystringRecommendedUnique 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)

ParameterTypeStatusDescription
transactionIdstringRequiredIdentifier of the settled transaction to refund (e.g. TXN_C2B_84920199).
amountnumberRequiredAmount in base currency to reverse back to customer. Must be less than or equal to original transaction value.
reasonstringOptionalExplanation 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"
}