Transaction

Transaction event and its lifecycle history. Amounts are integer minor currency units. metadata belongs to this event; retain event_id for outcome recovery.

  • 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: Additional Detailsnullable

    Additional transaction details as key-value pairs

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

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

  • device_type
    Type: string | null

    Device family that captured the transaction.

  • 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: Gateway Transaction Responsenullable

    Raw response from the payment gateway

    Properties: 1
  • history
    Type: array of objectnullable

    Historical events for this transaction

    Properties: 1
  • location_id
    Type: string | null

    Location/store ID where transaction occurred

  • merchant_name
    Type: string | null

    Name of the merchant for this transaction

  • metadata
    Type: Metadatanullable
    Properties: 1
  • owner_id
    Type: string | null
  • parent_account_ids
    Type: array of stringnullable
  • 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

  • psp
    Type: string | null

    Payment service provider that owns the processing relationship.

  • refunded
    Type: integernullable

    Total amount refunded in cents

  • reversed
    Type: integernullable

    Total amount reversed in cents

  • status
    Type: string | null

    Current transaction status

  • status_reason
    Type: stringnullable

    Reason for the current transaction status

  • surcharge_amount
    Type: integernullable

    Surcharge amount in cents

  • surcharge_applied
    Type: boolean

    Whether a surcharge was applied to this transaction

  • surcharge_basis
    Type: stringnullable

    Amount used to calculate percentage-based surcharges. Use the first non-null value from location, then terminal, then account. Defaults to total when all levels are null.

  • surcharge_confirmation_required
    Type: boolean | null

    Whether the cardholder must confirm the surcharge before the sale proceeds. Use the first non-null value from location, then terminal, then account. Defaults to no confirmation when all levels are null.

  • surcharge_rate
    Type: numbernullable

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

  • surcharge_source
    Type: stringnullable

    Which level of the cascade supplied the resolved surcharge rate and basis: the caller's own breakdown, or the location, terminal, or account default.

  • tax_amount
    Type: integernullable

    Tax amount in cents

  • tax_basis
    Type: stringnullable

    Amount used to calculate percentage-based tax. Use the first non-null value from location, then terminal, then account. Defaults to total (subtotal plus tip) when all levels are null. Use subtotal to exclude the tip.

  • tax_rate
    Type: integernullable

    Tax rate in basis points; 850 means 8.5%.

  • tax_source
    Type: stringnullable

    Which level of the cascade supplied the resolved tax rate and basis: the caller's own breakdown, or the location, terminal, or account default.

  • terminal_details
    Type: Terminal Detailsnullable

    Snapshot of the terminal configuration in force when the transaction was taken.

    Properties: 1
  • tip_amount
    Type: integernullable

    Tip amount in cents

  • tip_capture_mode
    Type: stringnullable

    When the tip was attached: tip_at_sale if recorded on the original sale, tip_adjust if added later by a tip adjustment. Tips added via tip_adjust are never included in the surcharge calculation.

  • tip_type
    Type: stringnullable

    Type of tip calculation method

  • transaction_type
    Type: string | null

    Type of transaction operation