Event: payment.failed

When it fires

A charge against a subscription’s payment method has been declined. The transaction is recorded with a declineCode from the gateway.

The subscription’s status is not changed by a single failed charge — Topiic does not yet automatically transition to PastDue. Listen for subscription.cancelled if a merchant subsequently cancels a chronically-failing subscription.

Headers

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

Body

{
  "id": "6a2e9b48-…",
  "type": "payment.failed",
  "createdAt": "2026-07-01T03:00:14.117Z",
  "data": {
    "transactionId":         "4d8c2a14-7b3d-4e9c-8d6f-1a2b3c4d5e6f",
    "originalTransactionId": "1f9e8d7c-6b5a-4e3d-2c1b-0a9f8e7d6c5b",
    "subscriptionId":        "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
    "memberId":              "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "amount":                49.50,
    "currency":              "AUD",
    "status":                "Declined",
    "declineCode":           "51",
    "occurredAt":            "2026-07-01T03:00:14.000Z"
  }
}

data fields

Field	Type	Notes
transactionId	UUID	The Topiic Transaction id for this failed attempt.
originalTransactionId	UUID | null	The original transaction this is a retry of, if any.
subscriptionId	UUID | null	The Subscription the charge belongs to.
memberId	UUID	The Topiic Member id.
amount	decimal	Attempted amount.
currency	string	ISO-4217 code.
status	string	Always "Declined" (or another non-Approved status).
declineCode	string | null	Gateway-supplied decline code. Common codes: "51" insufficient funds, "54" expired card, "05" do not honour.
occurredAt	ISO-8601 UTC	When the gateway returned the decline.

What to do on receipt

1. Verify the signature, dedupe on event.id.
2. Find the customer on your side via memberId.
3. Decide on a dunning response: send a “payment failed” email, prompt the customer to update their card, optionally restrict access after N failed attempts.
4. Don’t auto-retry from your side — Topiic will retry on its own schedule (when automatic recurring billing ships) and merchants can manually retry via the portal. Spamming the gateway with parallel retries causes lockouts.
5. Return 2xx within 10 seconds.

Caution

declineCode values come from the gateway and aren’t perfectly standardised. Use them for analytics (“how many cards are expiring?”) but don’t branch business logic on a specific code without testing — gateways change codes between versions.