Skip to main content
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

PropertyTypeDescription
rootfi_idintegerUnique identifier for this transaction
rootfi_created_atstringWhen this transaction was created in Commenda’s system (ISO 8601)
rootfi_updated_atstringWhen this transaction was last updated (ISO 8601)
rootfi_company_idintegerCompany identifier this transaction belongs to
platform_idstringPlatform-specific transaction identifier
typeenumType of transaction (payment, refund, credit_note, etc.)
invoice_idstringReference to the associated Invoice
order_idstringReference to the associated Order (if applicable)
subscription_idstringReference to the associated Subscription (for recurring payments)
contact_idstringReference to the Contact
currency_idstringISO 4217 currency code
amountnumberTransaction amount (always positive; type indicates direction)
statusenumCurrent status of the transaction
payment_method_typeenumPayment method used (for payments)
gatewaystringPayment gateway/processor name (e.g., “stripe”, “razorpay”)
gateway_transaction_idstringPlatform-specific transaction ID from the gateway
original_transaction_idstringFor refunds/reversals, reference to the original payment
reference_numberstringHuman-readable reference number
descriptionstringHuman-readable description of the transaction
reasonenumStandardized reason code (primarily for refunds/credit notes)
reason_codestringPlatform-specific reason code
metadataobjectAdditional platform-specific data
created_atstringOriginal transaction timestamp from platform (ISO 8601)
updated_atstringLast update timestamp from platform (ISO 8601)

​
Type Enum Values

ValueDescription
paymentContact payment received
refundMoney returned to contact
credit_noteCredit applied to contact account
feeProcessing fee or platform charge
chargebackPayment disputed and reversed by contact’s bank
payoutTransfer to merchant/vendor account
adjustmentManual adjustment to balance

​
Status Enum Values

ValueDescription
pendingTransaction is being processed
completedTransaction successfully completed
failedTransaction failed to process
cancelledTransaction was cancelled before completion
reversedTransaction was reversed after completion
unknownStatus cannot be determined

​
Payment Method Type Enum Values

ValueDescription
cardCredit or debit card payment
bank_transferDirect bank transfer or ACH
wire_transferWire transfer
paypalPayPal payment
apple_payApple Pay
google_payGoogle Pay
checkCheck payment
cashCash payment
cryptoCryptocurrency payment
otherOther payment method
unknownPayment method cannot be determined

​
Reason Enum Values (for refunds and credit notes)

ValueDescription
customer_requestContact requested the refund/credit
duplicateDuplicate charge
fraudFraudulent transaction
quality_issueProduct or service quality issue
billing_errorBilling mistake
loyalty_discountLoyalty program credit
promotionalPromotional credit or discount
adjustmentManual adjustment
otherOther 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=completed - 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": "completed",
  "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": "completed",
  "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": "completed",
  "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"
}