Transaction

Model to represent a transaction

  • account_id
    Type: string
    required

    Account ID of the merchant that owns this transaction

  • apple_transaction_id
    Type: string
    required

    Apple Pay transaction identifier

  • card
    Type: string
    required

    Masked card number (e.g., '****1234')

  • card_brand
    Type: string
    required

    Card brand (e.g., 'VISA', 'MASTERCARD', 'AMEX')

  • card_type
    Type: string
    required

    Type of card used ('Credit' or 'Debit')

  • created_at
    Type: integer
    required

    Transaction creation timestamp in milliseconds since epoch

  • currency
    Type: string
    required

    ISO 4217 currency code (e.g., 'USD', 'EUR')

  • event_id
    Type: string
    required

    Unique identifier for this specific transaction event (for idempotency)

  • mid
    Type: string
    required

    Merchant ID assigned by Koard

  • payment_method
    Type: string
    required

    Payment method used (e.g., 'apple_pay', 'credit_card')

  • processor_mid
    Type: string
    required

    Merchant ID assigned by the payment processor (e.g., PayRoc)

  • processor_tid
    Type: string
    required

    Terminal ID assigned by the payment processor

  • reader_identifier
    Type: string
    required

    Unique identifier for the card reader device

  • subtotal
    Type: integer
    required

    Subtotal amount in cents (before tax, tip, and surcharge)

  • tid
    Type: string
    required

    Terminal ID assigned by Koard

  • total_amount
    Type: integer
    required

    Total transaction amount in cents (subtotal + tax + tip + surcharge)

  • transaction_id
    Type: string
    required

    Unique identifier for the transaction across all events

  • additional_details
    Type: object | null

    Additional transaction details as key-value pairs

  • batch_id
    Type: string | null
  • device_id
    Type: string | null

    Physical device identifier (e.g., iPad serial number)

  • gateway
    Type: string | null

    Payment gateway used for processing

  • gateway_transaction_id
    Type: string | null

    Transaction ID returned by the payment gateway

  • gateway_transaction_response
    Type: object | null

    Raw response from the payment gateway

  • history
    Type: array of object | null

    Historical events for this transaction

  • location_id
    Type: string | null

    Location/store ID where transaction occurred

  • merchant_name
    Type: string | null

    Name of the merchant for this transaction

  • owner_id
    Type: string | null
  • parent_account_ids
    Type: array of string | null
  • processor
    Type: string | null

    Payment processor name (e.g., 'payroc', 'stripe')

  • processor_response_code
    Type: string | null

    Response code from the payment processor

  • processor_response_message
    Type: string | null

    Response message from the payment processor

  • refunded
    Type: integer | null

    Total amount refunded in cents

  • reversed
    Type: integer | null

    Total amount reversed in cents

  • status
    Type: string | null

    Current transaction status

  • status_reason
    Type: string | null

    Reason for the current transaction status

  • surcharge_amount
    Type: integer | null

    Surcharge amount in cents

  • surcharge_applied
    Type: boolean

    Whether a surcharge was applied to this transaction

  • surcharge_rate
    Type: number | null

    Surcharge rate as a decimal (e.g., 0.035 = 3.5%)

  • tax_amount
    Type: integer | null

    Tax amount in cents

  • tax_rate
    Type: number | null

    Tax rate as a percentage (e.g., 8.5 = 8.5%)

  • tip_amount
    Type: integer | null

    Tip amount in cents

  • tip_type
    Type: string | null

    Type of tip calculation method

  • transaction_type
    Type: string | null

    Type of transaction operation