Overview - Integrations by Commenda

The Transaction Data Model represents all monetary movements in the payment system. This unified model consolidates what were previously separate Payment, Refund, and Credit Note models. Transactions are distinguished by their type field.

Unified financial movements: All payments, refunds, credit notes, fees, chargebacks, and payouts in a single model
Type-based filtering: Query by transaction type to get specific financial movements
Complete audit trail: Full relationship tracking to invoices, orders, subscriptions, and original transactions
Gateway integration: Detailed payment gateway information and transaction IDs

Attributes

Transaction Attributes

Property	Type	Description
rootfi_id	integer	Unique identifier for this transaction
rootfi_created_at	string	When this transaction was created in Commenda’s system (ISO 8601)
rootfi_updated_at	string	When this transaction was last updated (ISO 8601)
rootfi_company_id	integer	Company identifier this transaction belongs to
platform_id	string	Platform-specific transaction identifier
type	enum	Type of transaction (`PAYMENT`, `REFUND`, `CREDIT_NOTE`, etc.)
invoice_id	string	Reference to the associated Invoice
order_id	string	Reference to the associated Order (if applicable)
subscription_id	string	Reference to the associated Subscription (for recurring payments)
contact_id	string	Reference to the Contact
currency_id	string	ISO 4217 currency code
amount	number	Transaction amount (always positive; type indicates direction)
status	enum	Current status of the transaction
payment_method_type	enum	Payment method used (for payments)
gateway	string	Payment gateway/processor name (e.g., “stripe”, “razorpay”)
gateway_transaction_id	string	Platform-specific transaction ID from the gateway
original_transaction_id	string	For refunds/reversals, reference to the original payment
reference_number	string	Human-readable reference number
description	string	Human-readable description of the transaction
reason	enum	Standardized reason code (primarily for refunds/credit notes)
reason_code	string	Platform-specific reason code
metadata	object	Additional platform-specific data
created_at	string	Original transaction timestamp from platform (ISO 8601)
updated_at	string	Last update timestamp from platform (ISO 8601)

Type Enum Values

Value	Description
`PAYMENT`	Contact payment received
`REFUND`	Money returned to contact
`CREDIT_NOTE`	Credit applied to contact account
`FEE`	Processing fee or platform charge
`CHARGEBACK`	Payment disputed and reversed by contact’s bank
`PAYOUT`	Transfer to merchant/vendor account
`ADJUSTMENT`	Manual adjustment to balance

Status Enum Values

Value	Description
`AUTHORIZED`	Transaction has been authorized but not yet captured
`CANCELED`	Transaction was canceled before completion
`FAILED`	Transaction failed to process
`PAID`	Transaction payment was successfully captured
`PENDING`	Transaction is being processed
`REFUNDED`	Transaction funds were returned or credited back
`REQUIRES_ACTION`	Transaction requires additional action before it can be completed
`REVERSED`	Transaction was reversed after completion
`UNKNOWN`	Status cannot be determined

Payment Method Type Enum Values

Value	Description
`CARD`	Credit or debit card payment
`BANK_TRANSFER`	Direct bank transfer or ACH
`WIRE_TRANSFER`	Wire transfer
`PAYPAL`	PayPal payment
`APPLE_PAY`	Apple Pay
`GOOGLE_PAY`	Google Pay
`CHECK`	Check payment
`CASH`	Cash payment
`CRYPTO`	Cryptocurrency payment
`OTHER`	Other payment method
`UNKNOWN`	Payment method cannot be determined

Reason Enum Values (for refunds and credit notes)

Value	Description
`CUSTOMER_REQUEST`	Contact requested the refund/credit
`DUPLICATE`	Duplicate charge
`FRAUD`	Fraudulent transaction
`QUALITY_ISSUE`	Product or service quality issue
`BILLING_ERROR`	Billing mistake
`LOYALTY_DISCOUNT`	Loyalty program credit
`PROMOTIONAL`	Promotional credit or discount
`ADJUSTMENT`	Manual adjustment
`OTHER`	Other reason

Expandable Attributes

Use the expand query parameter to include related objects:

expand=invoice - Includes full Invoice object
expand=order - Includes full Order object
expand=subscription - Includes full Subscription object
expand=contact - Includes full Contact object
expand=original_transaction - For refunds, includes the original payment

Filtering Options

Filter transactions by type using query parameters:

GET /v4/transactions?type=PAYMENT - Get all payments
GET /v4/transactions?type=REFUND - Get all refunds
GET /v4/transactions?type=CREDIT_NOTE - Get all credit notes
GET /v4/transactions?invoice_id=:id - Get all transactions for an invoice
GET /v4/transactions?subscription_id=:id - Get all transactions for a subscription
GET /v4/transactions?status=PAID - Filter by status
GET /v4/transactions?gateway=stripe - Filter by payment gateway

{
  "rootfi_id": 8001,
  "rootfi_created_at": "2025-01-05T12:00:00Z",
  "rootfi_updated_at": "2025-01-05T12:00:00Z",
  "rootfi_company_id": 999,
  "platform_id": "pay_stripe_001",
  "type": "PAYMENT",
  "invoice_id": "54321",
  "order_id": "ord_001",
  "subscription_id": "sub_001",
  "contact_id": "12345",
  "currency_id": "USD",
  "amount": 1075.00,
  "status": "PAID",
  "payment_method_type": "CARD",
  "gateway": "stripe",
  "gateway_transaction_id": "ch_stripe_12345",
  "reference_number": "TXN-2025-001",
  "description": "Payment for INV-2025-001",
  "created_at": "2025-01-05T12:00:00Z",
  "updated_at": "2025-01-05T12:00:00Z"
}

{
  "rootfi_id": 8002,
  "rootfi_created_at": "2025-01-10T10:00:00Z",
  "rootfi_updated_at": "2025-01-10T10:00:00Z",
  "rootfi_company_id": 999,
  "platform_id": "ref_stripe_001",
  "type": "REFUND",
  "original_transaction_id": "8001",
  "invoice_id": "54321",
  "contact_id": "12345",
  "currency_id": "USD",
  "amount": 100.00,
  "status": "REFUNDED",
  "reason": "CUSTOMER_REQUEST",
  "reason_code": "requested_by_customer",
  "gateway": "stripe",
  "gateway_transaction_id": "re_stripe_12345",
  "reference_number": "REF-2025-001",
  "description": "Partial refund",
  "metadata": {
    "original_payment_id": "8001"
  },
  "created_at": "2025-01-10T10:00:00Z",
  "updated_at": "2025-01-10T10:00:00Z"
}

{
  "rootfi_id": 8003,
  "rootfi_created_at": "2025-01-12T14:00:00Z",
  "rootfi_updated_at": "2025-01-12T14:00:00Z",
  "rootfi_company_id": 999,
  "platform_id": "cn_stripe_001",
  "type": "CREDIT_NOTE",
  "invoice_id": "54321",
  "contact_id": "12345",
  "currency_id": "USD",
  "amount": 50.00,
  "status": "REFUNDED",
  "reason": "LOYALTY_DISCOUNT",
  "reason_code": "promotional",
  "gateway": "stripe",
  "reference_number": "CN-2025-001",
  "description": "Loyalty program credit",
  "created_at": "2025-01-12T14:00:00Z",
  "updated_at": "2025-01-12T14:00:00Z"
}

Documentation Index

​Attributes

​Transaction Attributes

​Type Enum Values

​Status Enum Values

​Payment Method Type Enum Values

​Reason Enum Values (for refunds and credit notes)

​Expandable Attributes

​Filtering Options