# Create Refund

Initiate a refund for one or more invoices, charges, or as a standalone refund.

Refund Types:
- Invoice Refund: Refund one or more invoices
- Charge Refund: Refund one or more specific charges
- Standalone Refund: Refund without reference to an invoice/charge

Process:
1. Refund request is validated
2. Billing Service calls Payment API to process refund
3. On success, journal entries are created (DR Refund Expense, CR Bank)
4. Optionally, receipt is sent via Receipt Service

Endpoint: POST /refunds
Version: 1.0.0
Security: OAuth2

## Request fields (application/json):

  - `refundType` (string, required)
    Type of refund to process
    Enum: "INVOICE", "CHARGE", "STANDALONE"

  - `invoiceIds` (array)
    Invoice IDs to refund (required if refundType is INVOICE)

  - `chargeIds` (array)
    Charge IDs to refund (required if refundType is CHARGE)

  - `accountId` (string)
    Account to refund to (required for STANDALONE)

  - `amount` (integer, required)
    Refund amount in cents

  - `reason` (string)
    Reason for the refund

  - `sendReceipt` (boolean)
    Whether to send a receipt via Receipt Service

  - `metadata` (object)
    Additional metadata for the refund

## Response 201 fields (application/json):

  - `id` (string, required)

  - `entityId` (string, required)

  - `refundType` (string, required)
    Enum: "INVOICE", "CHARGE", "STANDALONE"

  - `invoiceIds` (array)

  - `chargeIds` (array)

  - `accountId` (string)

  - `amount` (integer, required)

  - `status` (string, required)
    Enum: "PENDING", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED"

  - `reason` (string)

  - `paymentTransactionId` (string)
    Payment gateway transaction ID

  - `journalEntryId` (string)
    Linked journal entry

  - `failureReason` (string)
    Reason for failure (if status is FAILED)

  - `metadata` (object)

  - `optimisticLockVersion` (integer)
    Optimistic locking version (managed by Hibernate @Version). Prevents concurrent update conflicts.

  - `createdAt` (string, required)

  - `updatedAt` (string)

  - `completedAt` (string)

## Response 400 fields (application/json):

  - `result` (object, required)

  - `result.status` (string, required)
    Response status (always ERROR for error responses)
    Enum: "ERROR"

  - `error` (object, required)

  - `error.responseCode` (string, required)
    Response code (numeric or contains numbers, e.g., "404", "409", "500", "ERR001")
    Example: "404"

  - `error.responseMessage` (array, required)
    Array of error message strings for multiple error details
    Example: ["Charge not found","The requested charge ID does not exist in the system"]

## Response 401 fields (application/json):

  - `result` (object, required)

  - `result.status` (string, required)
    Response status (always ERROR for error responses)
    Enum: "ERROR"

  - `error` (object, required)

  - `error.responseCode` (string, required)
    Response code (numeric or contains numbers, e.g., "404", "409", "500", "ERR001")
    Example: "404"

  - `error.responseMessage` (array, required)
    Array of error message strings for multiple error details
    Example: ["Charge not found","The requested charge ID does not exist in the system"]

## Response 404 fields (application/json):

  - `result` (object, required)

  - `result.status` (string, required)
    Response status (always ERROR for error responses)
    Enum: "ERROR"

  - `error` (object, required)

  - `error.responseCode` (string, required)
    Response code (numeric or contains numbers, e.g., "404", "409", "500", "ERR001")
    Example: "404"

  - `error.responseMessage` (array, required)
    Array of error message strings for multiple error details
    Example: ["Charge not found","The requested charge ID does not exist in the system"]