---
id: Transaction
name: Transaction
version: 1.0.0
identifier: transactionId
summary: Represents a low-level interaction with a payment gateway or processor (e.g., authorize, capture, refund, void).
owners:
  - dboyne

properties:
  - name: transactionId
    type: UUID
    required: true
    description: Unique identifier for this specific gateway transaction.
  - name: paymentId
    type: UUID
    required: true
    references: Payment
    relationType: hasOne
    description: Identifier of the parent Payment this transaction belongs to.
  - name: type
    type: string # (e.g., Authorize, Capture, Sale, Refund, Void, Verify)
    required: true
    description: The type of operation performed with the payment gateway.
  - name: gatewayReferenceId
    type: string
    required: true
    description: Unique transaction ID provided by the external payment gateway.
  - name: amount
    type: decimal
    required: true
    description: The amount associated with this specific transaction operation.
  - name: currency
    type: string # ISO 4217 code
    required: true
    description: Currency of the transaction amount.
  - name: status
    type: string # (e.g., Success, Failure, Pending)
    required: true
    description: Status reported by the gateway for this specific operation.
  - name: responseCode # Gateway-specific code
    type: string
    required: false
    description: Response code returned by the payment gateway.
  - name: responseMessage # Gateway-specific message
    type: string
    required: false
    description: Detailed message or reason returned by the gateway.
  - name: processedAt
    type: DateTime
    required: true
    description: Timestamp when the transaction was processed by the gateway.
  - name: rawRequest # Optional, for debugging - consider security implications
    type: text
    required: false
    description: Raw request payload sent to the gateway (use with caution).
  - name: rawResponse # Optional, for debugging - consider security implications
    type: text
    required: false
    description: Raw response payload received from the gateway (use with caution).
---

## Overview

The Transaction entity logs the individual interactions with an external payment processor (like Stripe, PayPal, Adyen) that occur as part of processing a `Payment`. This provides a detailed audit trail of gateway operations, including authorizations, captures, refunds, and any associated success or failure responses.

### Entity Properties

<EntityPropertiesTable />

## Relationships

- **Payment:** A transaction is part of one `Payment`.

## Examples

- **Authorization Success:** Type: Authorize, PaymentID: PAY-98765, GatewayRef: auth_abc, Amount: $19.99, Status: Success.
- **Capture Success:** Type: Capture, PaymentID: PAY-98765, GatewayRef: ch_def, Amount: $19.99, Status: Success (following the authorization).
- **Authorization Failure:** Type: Authorize, PaymentID: PAY-98766, GatewayRef: auth_ghi, Amount: $50.00, Status: Failure, ResponseCode: 'declined', ResponseMessage: 'Insufficient Funds'.
- **Refund Success:** Type: Refund, PaymentID: PAY-98760, GatewayRef: re_jkl, Amount: $25.00, Status: Success.
