Transaction

Model to represent a transaction

  • account_id
    Type: string · Account Id
    required

    Account ID of the merchant that owns this transaction

  • apple_transaction_id
    Type: string · Apple Transaction Id
    required

    Apple Pay transaction identifier

  • card
    Type: string · Card
    required

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

  • card_brand
    Type: string · Card Brand
    required

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

  • card_type
    Type: string · Card Type
    required

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

  • created_at
    Type: integer · Created At
    required

    Transaction creation timestamp in milliseconds since epoch

  • currency
    Type: string · Currency
    required

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

  • event_id
    Type: string · Event Id
    required

    Unique identifier for this specific transaction event (for idempotency)

  • mid
    Type: string · Mid
    required

    Merchant ID assigned by Netevia

  • payment_method
    Type: string · Payment Method
    required

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

  • processor_mid
    Type: string · Processor Mid
    required

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

  • processor_tid
    Type: string · Processor Tid
    required

    Terminal ID assigned by the payment processor

  • reader_identifier
    Type: string · Reader Identifier
    required

    Unique identifier for the card reader device

  • subtotal
    Type: integer · Subtotal
    required

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

  • tid
    Type: string · Tid
    required

    Terminal ID assigned by Netevia

  • total_amount
    Type: integer · Total Amount
    required

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

  • transaction_id
    Type: string · Transaction Id
    required

    Unique identifier for the transaction across all events

  • additional_details
    Type: object | null · Additional Details

    Additional transaction details as key-value pairs

  • batch_id
    Type: string | null · Batch Id
  • device_id
    Type: string | null · Device Id

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

  • device_type
    Type: string | null · Device Type

    Device family that captured the transaction.

  • gateway
    Type: string | null · Gateway

    Payment gateway used for processing

  • gateway_transaction_id
    Type: string | null · Gateway Transaction Id

    Transaction ID returned by the payment gateway

  • gateway_transaction_response
    Type: object | null · Gateway Transaction Response

    Raw response from the payment gateway

  • history
    Type: array object[] | null · History

    Historical events for this transaction

    Empty object
  • location_id
    Type: string | null · Location Id

    Location/store ID where transaction occurred

  • merchant_name
    Type: string | null · Merchant Name

    Name of the merchant for this transaction

  • owner_id
    Type: string | null · Owner Id
  • parent_account_ids
    Type: array string[] | null · Parent Account Ids
  • processor
    Type: string | null · Processor

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

  • processor_response_code
    Type: string | null · Processor Response Code

    Response code from the payment processor

  • processor_response_message
    Type: string | null · Processor Response Message

    Response message from the payment processor

  • psp
    Type: string | null · Psp

    Payment service provider that owns the processing relationship.

  • refunded
    Type: integer | null · Refunded

    Total amount refunded in cents

  • reversed
    Type: integer | null · Reversed

    Total amount reversed in cents

  • status
    Type: string | null · Status

    Current transaction status

  • status_reason
    Type: string | null · Status Reasonenum

    Reason for the current transaction status

    values
    • approved
    • declined
    • surcharge_expired
    • surcharge_pending
    • surcharge_declined_by_payer
  • surcharge_amount
    Type: integer | null · Surcharge Amount

    Surcharge amount in cents

  • surcharge_applied
    Type: boolean · Surcharge Applied

    Whether a surcharge was applied to this transaction

  • surcharge_basis
    Type: string | null · Surcharge Basisenum

    What the surcharge is calculated on. Resolved most-specific-first: terminal, then location, then account. A null at the terminal or location level inherits from the level above; a null at the account level leaves it unset.

    values
    • total
    • subtotal
    • subtotal_plus_tax
    • subtotal_plus_tip
    • null
  • surcharge_confirmation_required
    Type: boolean | null · Surcharge Confirmation Required

    Whether the cardholder must confirm the surcharge before the sale proceeds. When true, sale/preauth returns a surcharge-pending state that must be confirmed before the transaction completes. Resolved most-specific-first: terminal, then location, then account. A null at the terminal or location level inherits from the level above; a null at the account level defaults to no confirmation.

  • surcharge_rate
    Type: number | null · Surcharge Rate

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

  • surcharge_source
    Type: string | null · Surcharge Sourceenum

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

    values
    • transaction
    • location
    • terminal
    • account
    • null
  • tax_amount
    Type: integer | null · Tax Amount

    Tax amount in cents

  • tax_basis
    Type: string | null · Tax Basisenum

    What the tax is calculated on. Resolved most-specific-first: terminal, then location, then account. A null at the terminal or location level inherits from the level above; a null at the account level leaves it unset.

    values
    • total
    • subtotal
    • null
  • tax_rate
    Type: number | null · Tax Rate

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

  • tax_source
    Type: string | null · Tax Sourceenum

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

    values
    • transaction
    • location
    • terminal
    • account
    • null
  • terminal_details
    Type: object | null · Terminal Details

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

    • propertyName
      Type: anything
  • tip_amount
    Type: integer | null · Tip Amount

    Tip amount in cents

  • tip_capture_mode
    Type: string | null · Tip Capture Modeenum

    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.

    values
    • tip_at_sale
    • tip_adjust
    • null
  • tip_type
    Type: string | null · Tip Typeenum

    Type of tip calculation method

    values
    • fixed
    • percentage
    • null
  • transaction_type
    Type: string | null · Transaction Type

    Type of transaction operation