Money Out

Refunds

Refund card transactions back to the cardholder's original card. Pass the transaction ID of the original charge with a reason, with support for partial refunds, status tracking, and webhook notifications.

Request

Request a refund of a previously settled card transaction by passing the transaction_id (tra_) of the original charge and a reason. The funds are returned to the card used on the original transaction — no card details are required.

The full transaction amount is refunded by default; pass amount for a partial refund. Multiple partial refunds may be issued against the same transaction, up to the original transaction amount in total. Only settled card transactions (transaction status PAID) can be refunded.

Card transaction IDs are returned by Checkout Link, Checkout Form, Card Vault Charge, and captured Card Vault Pre-Auth holds, or can be found via transactions.

Path

POST /refunds/{transaction_id}/request

Path Parameter	Type	Description	Example
transaction_id	String(32)	The original settled card transaction to refund — see transactions	tra_pr6CvR_4pvWwmgQ4y3dtY

Example (Basic)

Refund the full transaction amount.

{
  "reason": "Order cancelled by customer" // recorded against the refund and shown in reporting
}

Example (Advanced)

Partial refund with all options.

{
  "reason": "Item returned — partial refund for one of two items", // recorded against the refund and shown in reporting

  "amount": "150.00", // [optional] must be <= the remaining refundable amount; omit to refund in full

  "reference": "REF-2026-00042", // [optional] your reference for this refund; defaults to the original transaction reference

  "signature": "secret-key-for-payload", // [optional] shared-secret signature for the payload, see the signature section below

  "notification": {
    "email": "me@my-email.co.za", // [optional] email notification on the refund outcome
    "webhook_url": "https://merchant.example/webhooks/payments" // webhook on refund.successful / refund.failed
  },

  "metadata": {
    "order_id": "ord_98765" // [optional] custom key/value pairs returned on the refund and webhooks
  }
}

Request Parameters

Field	Required	Type	Description	Example
reason	Y	String(512)	Reason for the refund; recorded against the refund and shown in reporting	Order cancelled by customer
amount	N	String	Amount to refund; must be less than or equal to the remaining refundable amount. Omit to refund the full transaction	150.00
reference	N	String(35)	Your reference for this refund; defaults to the original transaction reference	REF-2026-00042
signature	N	String	Optional passphrase signature for verifying the payload	secret-key-for-payload
notification.email	N	String	Email address to notify on the refund outcome	me@my-email.co.za
notification.webhook_url	N	String	Webhook URL for the refund outcome	https://merchant.example/webhooks/payments
metadata	N	Object	Custom key/value metadata returned on the refund and webhooks	`{"order_id": "ord_98765"}`

Response Body

A refund (ref_) is created against the original transaction (tra_). Refunds are submitted to the card schemes for processing and are typically reflected on the cardholder's statement within 3–5 business days; the refund is created with status PENDING and moves to REFUNDED or FAILED once processed — see the webhook section for outcome notifications.

{
    "status": true,
    "result": {
      "id": "ref_Hj4TmN8wQxLv2pYcE6aBz",
      "transaction_id": "tra_pr6CvR_4pvWwmgQ4y3dtY",
      "customer_id": "cus_abc123...",
      "refund_status": "PENDING",
      "amount": "150.00",
      "refundable_amount": "199.00",
      "currency": "ZAR",
      "reference": "REF-2026-00042",
      "reason": "Item returned — partial refund for one of two items",
      "created_at": "2026-07-06T10:15:30Z"
    }
}

Response Parameters

Field	Type	Description	Example
status	Boolean	Whether the refund request was accepted	true
result.id	String(32)	Unique refund identifier	ref_Hj4TmN8wQxLv2pYcE6aBz
result.transaction_id	String(32)	The original transaction being refunded	tra_pr6CvR_4pvWwmgQ4y3dtY
result.customer_id	String(32)	Customer associated with the original transaction, when applicable	cus_abc123...
result.refund_status	ENUM	Refund state: `PENDING`, `REFUNDED`, or `FAILED`, see lookups	`PENDING`
result.amount	String	Amount being refunded	150.00
result.refundable_amount	String	Amount still refundable on the original transaction after this refund	199.00
result.currency	String(3)	ISO 4217 currency code	`ZAR`
result.reference	String(35)	Reference used for the refund	REF-2026-00042
result.reason	String(512)	Reason supplied on the refund request	Item returned — partial refund for one of two items
result.created_at	String	ISO timestamp when the refund was created	2026-07-06T10:15:30Z

List

List the refunds on the platform.

Path

GET /refunds/list?{params}

Query Parameters

Field	Required	Type	Description	Example
refund_id	N	String(32)	ID of a specific refund to search for.	ref_Hj4TmN8wQxLv2pYcE6aBz
transaction_id	N	String(32)	Original transaction ID to filter for.	tra_pr6CvR_4pvWwmgQ4y3dtY
customer_id	N	String(32)	ID of a customer to search for.	cus_cldM8OIXkGwBrfd5jjPdD
reference	N	String(35)	Refund reference to filter for.	REF-2026-00042
refund_status	N	ENUM	Filter for specific refund statuses. (`PENDING`,`REFUNDED`,`FAILED`)	REFUNDED
date_created_start	N	Date(YYYY-MM-DD)	Filter for records created on or after this date.	2026-05-21
date_created_end	N	Date(YYYY-MM-DD)	Filter for records created up to this date.	2026-05-22

Response Body

{
  "status": true,
  "records": [{
    "id": "ref_Hj4TmN8wQxLv2pYcE6aBz",
    "transaction_id": "tra_pr6CvR_4pvWwmgQ4y3dtY",
    "customer_id": "cus_abc123...",
    "refund_status": "REFUNDED",
    "amount": "150.00",
    "currency": "ZAR",
    "reference": "REF-2026-00042",
    "reason": "Item returned — partial refund for one of two items",
    "metadata": {
      "order_id": "ord_98765"
    },
    "created_at": "2026-07-06T10:15:30Z",
    "completed_at": "2026-07-09T08:00:00Z"
  }, ...]
}

Response Parameters

Field	Type	Description	Example
status	Boolean	true - success, false - error	true
records	Array of objects
*.id	String(32)	Unique refund identifier	ref_Hj4TmN8wQxLv2pYcE6aBz
*.transaction_id	String(32)	The original transaction that was refunded	tra_pr6CvR_4pvWwmgQ4y3dtY
*.customer_id	String(32)	Customer associated with the original transaction, when applicable	cus_abc123...
*.refund_status	ENUM	(`PENDING`,`REFUNDED`,`FAILED`), see lookups	`REFUNDED`
*.amount	String	Refunded amount	150.00
*.currency	String(3)	ISO 4217 currency code	`ZAR`
*.reference	String(35)	Reference used for the refund	REF-2026-00042
*.reason	String(512)	Reason supplied on the refund request	Item returned — partial refund for one of two items
*.metadata	Object	Custom key/value metadata supplied on the refund request	`{"order_id": "ord_98765"}`
*.created_at	String	ISO timestamp when the refund was created	2026-07-06T10:15:30Z
*.completed_at	String	ISO timestamp when the refund reached its final status; `null` while pending	2026-07-09T08:00:00Z

Signature creation

When creating API keys on the dashboard you can download a passphrase key, use it to generate your signature and send it in the signature parameter. The canonicalization and HMAC-SHA256 process is identical across all endpoints — see Checkout Link — Signature creation for Node.js, PHP, C#, Java, and Python examples.

Webhook

When a refund completes or fails, a webhook may be delivered to notification.webhook_url when that field was supplied on the refund request. Broader platform webhooks are configured separately if applicable.

Possible event values include refund.successful and refund.failed, listed under Webhook events.

Webhook Payload

{
  // refund.successful · refund.failed
  "event": "refund.successful",
  "data": [
    {
      "refund": {
        "id": "ref_Hj4TmN8wQxLv2pYcE6aBz",
        "transaction_id": "tra_pr6CvR_4pvWwmgQ4y3dtY",
        "customer_id": "cus_abc123...",
        "refund_status": "REFUNDED",
        "amount": "150.00",
        "currency": "ZAR",
        "reference": "REF-2026-00042",
        "reason": "Item returned — partial refund for one of two items",
        "metadata": {
          "order_id": "ord_98765"
        },
        "completed_at": "2026-07-09T08:00:00Z"
      }
    }
  ],
  "created_at": "2026-07-09T08:00:00Z"
}

Webhook Payload Parameters

Field	Type	Description	Example
event	String	Type of webhook event that occurred	refund.successful
data	Array	Array containing refund data	...
data.refund.id	String(32)	Unique refund identifier	ref_Hj4TmN8wQxLv2pYcE6aBz
data.refund.transaction_id	String(32)	The original transaction that was refunded	tra_pr6CvR_4pvWwmgQ4y3dtY
data.refund.customer_id	String(32)	Customer associated with the original transaction, when applicable	cus_abc123...
data.refund.refund_status	ENUM	Refund state after the event, see lookups	`REFUNDED`
data.refund.amount	String	Refunded amount	150.00
data.refund.currency	String(3)	ISO 4217 currency code	`ZAR`
data.refund.reference	String(35)	Reference used for the refund	REF-2026-00042
data.refund.reason	String(512)	Reason supplied on the refund request	Item returned — partial refund for one of two items
data.refund.metadata	Object	Custom key/value metadata supplied on the refund request	`{"order_id": "ord_98765"}`
data.refund.completed_at	String	ISO timestamp when the refund reached its final status	2026-07-09T08:00:00Z
created_at	String	ISO timestamp when webhook was created	2026-07-09T08:00:00Z

Webhook Events

Event	Description	Trigger Condition	Data Included
`refund.successful`	The refund was processed and the funds returned to the cardholder	When the card scheme confirms the refund	Refund details, original transaction reference
`refund.failed`	The refund could not be processed	When the card scheme rejects the refund (e.g. the original card account is closed)	Refund details with failure reason

Webhook Security

All webhooks are sent with the following headers for verification:

X-Signature: HMAC-SHA256 signature of the payload
X-Timestamp: Unix timestamp of when the webhook was sent
User-Agent: Kwik-Webhooks/1.0

Webhook Response

Your endpoint should respond with a 200 status code to acknowledge receipt. Failed webhooks will be retried up to 3 times with exponential backoff.

Recipients

Manage recipient records for use with payouts.

CDV

Validate South African account numbers using Check Digit Verification algorithms. Ensure data integrity and reduce collection failures by verifying customer identification and bank account details before processing.