ReservationCommand (v1.0.0)

Command to reserve an amount in a merchant account for future transactions

Command Collecting MerchantAccountAggregate

ReservationCommand

Creates a reservation on a merchant account as part of the refund authorization process, ensuring sufficient funds are available for the potential refund.

Schema

schema.json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "ReservationCommand",
  "description": "Command to reserve an amount 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 to reserve (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"
    }
  },
  "required": ["accountId", "reservationId", "amount", "currency", "accountType"],
  "additionalProperties": false
}

Purpose

This command verifies the merchant’s balance and reserves the specified amount for a potential refund. The reservation ensures that funds are held and available when the refund is confirmed, preventing insufficient balance issues during refund processing.

Key Attributes

  • Account ID: Merchant account aggregate identifier
  • Transaction ID: Unique identifier for the transaction requiring reservation
  • Amount: Amount to be reserved for the potential refund
  • Currency: Currency of the reservation amount
  • Refund Reference: Reference to the refund request requiring the reservation
  • Expiry Date: Optional expiration date for the reservation

Business Rules

  • Account must have sufficient available balance for the reservation
  • Currency must match the merchant account currency
  • Amount must be positive and greater than zero
  • Only one active reservation per transaction ID is allowed
  • Reservations reduce available balance but don’t affect total balance
  • Expired reservations are automatically released

Reservation Process

  1. Balance Verification: Check if sufficient funds are available
  2. Amount Reservation: Hold the specified amount from available balance
  3. Tracking: Record reservation details for future release or confirmation
  4. Event Generation: Produce AmountReservedEvent upon successful reservation

Usage Scenarios

  • Refund Authorization: Initial step in refund processing workflow
  • Pre-authorization: Holding funds before final refund confirmation
  • Risk Management: Ensuring funds availability for disputed transactions
  • Balance Management: Temporary allocation of funds for pending operations

Result

When successful, this command produces an AmountReservedEvent and updates the merchant account to reflect the reserved amount, reducing available balance while maintaining total balance.

Edit this page