Payment Failed

Emitted when a payment attempt fails due to authorization decline, gateway error, or other issues

Event Domain Event

Overview

The PaymentFailed event indicates that a payment attempt was unsuccessful. This could be due to insufficient funds, card decline, gateway timeout, or validation errors.

When is this event emitted?

This event is published when:

  1. Payment authorization is declined
  2. Gateway returns an error
  3. Validation fails (expired card, invalid CVV)
  4. Technical errors prevent processing
  5. Fraud checks fail

Event Schema

Schema Definition

{
  "eventId": "uuid",
  "eventType": "PaymentFailed",
  "timestamp": "2025-12-11T10:30:00Z",
  "version": "1.0.0",
  "data": {
    "paymentId": "string",
    "attemptId": "string",
    "customerId": "string",
    "amount": {
      "value": "number",
      "currency": "string"
    },
    "paymentMethod": {
      "type": "string",
      "last4": "string"
    },
    "invoiceId": "string (optional)",
    "failureReason": "string",
    "errorCode": "string",
    "gatewayResponse": "string",
    "isRetryable": "boolean",
    "attemptNumber": "number",
    "failedAt": "timestamp"
  }
}

Failure Categories

Customer-side Issues (Not Retryable)

  • insufficient_funds: Not enough money in account
  • card_declined: Card issuer declined
  • expired_card: Card has expired
  • invalid_cvv: Security code incorrect

Technical Issues (Retryable)

  • gateway_timeout: Payment gateway didn’t respond
  • gateway_error: Temporary gateway issue
  • network_error: Connection problem

Fraud Prevention

  • fraud_suspected: Fraud checks failed
  • velocity_limit: Too many attempts in short time

Example Payload

{
  "eventId": "f1a2b3c4-d5e6-7f8a-9b0c-1d2e3f4a5b6c",
  "eventType": "PaymentFailed",
  "timestamp": "2025-12-11T10:35:00Z",
  "version": "1.0.0",
  "data": {
    "paymentId": "pay_9876543210",
    "attemptId": "att_xyz789",
    "customerId": "cus_johndoe",
    "amount": {
      "value": 99.99,
      "currency": "USD"
    },
    "paymentMethod": {
      "type": "credit_card",
      "last4": "4242"
    },
    "invoiceId": "INV-2025-000124",
    "failureReason": "Insufficient funds",
    "errorCode": "insufficient_funds",
    "gatewayResponse": "card_declined",
    "isRetryable": false,
    "attemptNumber": 1,
    "failedAt": "2025-12-11T10:35:00Z"
  }
}

Downstream Actions

  • Invoice Service: Marks payment attempt as failed
  • Notification Service: Notifies customer of failed payment
  • AR Service: May trigger dunning process if invoice overdue
  • Retry Service: Schedules retry for retryable failures
21 properties
eventIdstring<uuid>
required
eventTypestringconstant: PaymentFailed
required
timestampstring<date-time>
required
versionstring
required
Match pattern: ^\d+\.\d+\.\d+$
dataobject
required
Edit this page