Event: payment.refunded

When it fires

A merchant has refunded a previously-approved charge through the Topiic portal or POST /api/Transactions/{id}/refund. The refund may be full (the entire original amount) or partial (less than the original).

A refund creates a new Transaction row with a negative Amount and Status = Refunded; the original transaction is also marked Refunded. This webhook references the new refund transaction.

Headers

Same envelope as other events: Topiic-Event-Id, Topiic-Idempotency-Key, Topiic-Signature. See Verifying signatures.

Body

{
  "id": "2f8a3d54-…",
  "type": "payment.refunded",
  "createdAt": "2026-07-03T14:18:55.330Z",
  "data": {
    "transactionId":         "9c1e7b35-2d4f-4a8d-9c6b-3e5f7a1c8b2d",
    "originalTransactionId": "4d8c2a14-7b3d-4e9c-8d6f-1a2b3c4d5e6f",
    "subscriptionId":        "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
    "memberId":              "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "amount":                49.50,
    "currency":              "AUD",
    "reason":                "Class cancelled - goodwill refund",
    "occurredAt":            "2026-07-03T14:18:55.000Z"
  }
}

data fields

Field	Type	Notes
transactionId	UUID	The Topiic Transaction id for this refund (negative-amount row).
originalTransactionId	UUID	The Transaction that was refunded.
subscriptionId	UUID | null	The Subscription the original charge belonged to.
memberId	UUID	The Topiic Member id.
amount	decimal	Positive refund amount (the amount of money returned to the customer).
currency	string	ISO-4217 code.
reason	string | null	Free-text reason captured at refund time.
occurredAt	ISO-8601 UTC	When the gateway processed the refund.

What to do on receipt

1. Verify the signature, dedupe on event.id.
2. Find the customer on your side via memberId.
3. Record the refund in your billing history — link back to the original charge via originalTransactionId.
4. If your product gates feature access by amount paid (e.g. class pack purchases), recompute the balance.
5. Optionally trigger a “refund processed” email.
6. Return 2xx within 10 seconds.

Partial refunds

If the original transaction was $49.50 and only $20 was refunded, you’ll receive a payment.refunded event with amount: 20.00. The original transaction is still marked Refunded even though only a portion was returned — Topiic doesn’t currently distinguish “partially refunded” as a separate status. Use the sum of refund transactions against an original to decide whether the customer was made whole.