POST/v1/transactions/:id/refund

Refund transaction

Initiates a full or partial refund for a completed payment.

Authentication

Secret Key — send Authorization: Bearer YOUR_KEY header.

Feature required

One refund rule: a secret key refunds when its app's Refunds switch is on and an Admin has set the app's refund limits per currency in the dashboard (with two-step verification); a restricted key needs the refunds scope and refunds within its own limits. Send an Idempotency-Key header. A refund never exceeds what was captured and is audited.

Request parameters

Parameter	Type	Required	Description
`amount`	string	No	Partial refund amount; omit for full refund
`reason`	string	Yes	duplicate \| fraudulent \| customer_request \| other
`note`	string	No	Internal note (up to 500 characters)
`metadata`	object	No	Your own key-value pairs (strings), returned on the refund and in its events

Response fields

Field	Type	Description
`refund`	object	The refund: id, transactionId, amount, currency, reason, status (pending \| completed \| failed), metadata, createdAt
`originalTransaction`	object	The payment: id, status, refundedAmount

Code examples

bash

curl -X POST https://api.watenga.africa/v1/transactions/txn_01HQXYZ/refund \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Watenga-Version: 2026-10-29" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-order-1001" \
  -d '{
        "reason": "customer_request"
      }'

Response example

json

{
  "success": true,
  "data": {
    "refund": {
      "id": "6f1c2a7e-0b4d-4e0f-9a51-2f1f0c9e7a10",
      "transactionId": "0d8a6c55-2c1f-4f0e-8a3e-7d1b9f4e2c31",
      "amount": "25.0000",
      "currency": "USD",
      "reason": "customer_request",
      "status": "completed",
      "metadata": {},
      "createdAt": "2026-10-26T12:00:00.000Z"
    },
    "originalTransaction": { "id": "0d8a6c55-2c1f-4f0e-8a3e-7d1b9f4e2c31", "status": "reversed", "refundedAmount": "25.0000" }
  }
}