Refund Transactions

Return captured funds to the cardholder after a sale or captured preauth.

What You Learn

Difference between full and partial refunds
How to call the refund endpoint with optional amount fields
Expected response data and reconciliation tips
Interaction with surcharge and reporting totals

When to Refund

Issue a refund when:

The customer returns merchandise after capture
A captured amount needs to be partially returned (partial refund)
You must reverse a sale that has already been settled

If the funds were never captured, use a reverse instead.

Endpoint

POST /v1/payments/{transaction_id}/refund

transaction_id – The captured transaction ID
amount (optional) – Amount to refund in minor units (cents). Omit for a full refund.
event_id (optional) – Idempotency key

Request Example

POST /v1/payments/txn_123/refund
Content-Type: application/json
X-Koard-Apikey: <your-api-key>

{
  "amount": 5000,
  "event_id": "refund-5000"
}

Partial refunds: Koard updates refunded in the transaction record and keeps track of remaining refundable balance. You can send multiple refund requests as long as the total does not exceed the captured amount.

Response Fields to Store

status – Becomes refunded once the full amount is returned
refunded – Total amount refunded in minor units
surcharge_amount – Remains for reference; Koard does not automatically refund surcharges unless your business logic requires it
gateway_transaction_response – Contains processor-specific confirmation codes

Related Guides

Sale – Initiating one-step transactions
Capture – Capturing preauths before issuing refunds
Payment Lifecycle – Understand refund placement in the overall flow