AmountReservedEvent

Published when an amount is successfully reserved on a merchant account as part of the refund authorization process.

Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "AmountReservedEvent",
  "description": "Event emitted when an amount is reserved in a merchant account",
  "properties": {
    "accountId": {
      "type": "object",
      "description": "Account identifier",
      "properties": {
        "value": {
          "type": "string",
          "format": "uuid",
          "description": "The unique account UUID"
        }
      },
      "required": ["value"]
    },
    "reservationId": {
      "type": "object",
      "description": "Reservation identifier",
      "properties": {
        "value": {
          "type": "string",
          "format": "uuid",
          "description": "The unique reservation UUID"
        }
      },
      "required": ["value"]
    },
    "amount": {
      "type": "integer",
      "minimum": 0,
      "description": "Amount reserved (in smallest currency unit, e.g., 25000 = 250.00)",
      "example": 25000
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "description": "Currency of the reservation (ISO 4217)",
      "example": "EUR"
    },
    "accountType": {
      "type": "string",
      "description": "Type of account for the reservation",
      "example": "MerchantDebt"
    },
    "reference": {
      "type": "string",
      "description": "External reference for the reservation",
      "example": "refund-prep-67890"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp when the amount was reserved"
    }
  },
  "required": ["accountId", "reservationId", "amount", "currency", "accountType", "timestamp"],
  "additionalProperties": false
}

Purpose

This event indicates that funds have been held (reserved) from the merchant’s available balance to ensure sufficient funds are available for a potential refund. The reservation prevents the merchant from accessing these funds until the refund is either confirmed or the reservation is released.

Key Attributes

Account ID: Merchant account aggregate identifier where the reservation was made
Transaction ID: Unique identifier for the transaction requiring the reservation
Reserved Amount: Amount that has been reserved from available balance
Currency: Currency of the reserved amount
Reservation Timestamp: When the reservation was created
Refund Reference: Reference to the refund request that triggered the reservation
Available Balance: Updated available balance after reservation

Business Impact

Balance Reduction: Available balance is reduced by the reserved amount
Refund Guarantee: Ensures funds are available when refund is confirmed
Risk Mitigation: Prevents insufficient balance issues during refund processing
Cash Flow Management: Provides visibility into pending refund obligations

Integration Points

This event is consumed by:

Balance Views: To update available balance displays and reporting
Refund Processing: To track reservation status and amounts
Risk Management: For monitoring reserved amounts and exposure
Accounting Reports: For balance reconciliation and audit trails

Reservation Mechanics

The reservation process affects account balances as follows:

Total Balance: Remains unchanged (no actual funds movement)
Available Balance: Reduced by the reserved amount
Reserved Amount: Tracked separately for future release or confirmation
Transaction History: Records the reservation for audit purposes

Follow-up Actions

After this event, the reservation can be:

Released: Via ReleaseReservationCommand when refund is cancelled/expired
Confirmed: When the actual refund transaction is processed
Expired: Automatically released after a configured timeout period