Skip to main content
The Transaction Data Model represents all monetary movements in your e-commerce operations. V4 consolidates the previous separate Payment and Refund models into a single unified Transaction model, simplifying financial tracking and reporting.
  • Unified monetary tracking: All payments, refunds, chargebacks, and adjustments in one model.
  • Type-based filtering: Easily filter transactions by type (payment, refund, chargeback, etc.).
  • Complete payment details: Gateway information, payment methods, and transaction IDs included.
  • Refund linking: Refunds are linked to their original payment transactions for complete audit trails.

​
Key V4 Changes

In V4, the separate Payments and Refunds endpoints have been consolidated:
V3 EndpointV4 Endpoint
GET /v3/ecommerce/paymentsGET /v4/ecommerce/transactions?type=payment
GET /v3/ecommerce/refundsGET /v4/ecommerce/transactions?type=refund

​
Attributes

FieldTypeDescriptionRequiredExpandable
rootfi_idintegerUnique identifier for this transactionYesNo
rootfi_created_atdatetimeWhen this transaction was created in Commenda’s systemYesNo
rootfi_updated_atdatetimeWhen this transaction was last updatedYesNo
rootfi_company_idintegerCompany identifier this transaction belongs toYesNo
platform_idstringPlatform-specific transaction identifierYesNo
typeenumType of transaction (payment, refund, etc.)YesNo
order_idstringReference to the associated OrderYesYes
contact_idstringReference to the ContactNoYes
currency_idstringISO 4217 currency codeYesNo
amountdecimalTransaction amount (always positive, use type to determine direction)YesNo
statusenumCurrent status of the transactionYesNo
payment_method_typeenumPayment method used for this transactionNoNo
gatewaystringPayment processor or gateway name (e.g., “shopify”, “stripe”)NoNo
gateway_transaction_idstringTransaction ID from the payment gatewayNoNo
original_transaction_idstringFor refunds, reference to the original payment transactionNoYes
descriptionstringHuman-readable description of the transactionNoNo
reasonenumReason for the transaction (primarily used for refunds)NoNo
created_atdatetimeOriginal transaction timestamp from platformYesNo
updated_atdatetimeLast update timestamp from platformYesNo

​
Type Enum Values

ValueDescription
paymentContact payment received
refundMoney returned to contact
chargebackPayment disputed and reversed by contact’s bank
adjustmentManual adjustment to order total
feeProcessing or platform fee

​
Status Enum Values

ValueDescription
pendingTransaction is being processed
completedTransaction has been successfully completed
failedTransaction failed to process
cancelledTransaction was cancelled
reversedTransaction was reversed (similar to refund)
unknownStatus cannot be determined

​
Payment Method Type Enum Values

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

​
Reason Enum Values (for refunds)

ValueDescription
customer_requestContact requested a refund
fraudTransaction was fraudulent
duplicateDuplicate charge
quality_issueProduct quality or defect issue
not_receivedContact never received the product
cancelled_orderOrder was cancelled
otherOther reason

​
Expandable Attributes

  • expand=order - Includes full Order object
  • expand=contact - Includes full Contact object
  • expand=original_transaction - For refunds, includes the original payment transaction

​
Filtering Transactions

GET /v4/ecommerce/transactions?type=payment
GET /v4/ecommerce/transactions?type=refund
GET /v4/ecommerce/transactions?order_id=ord_123456
GET /v4/ecommerce/transactions?status=completed

{
  "rootfi_id": 8001,
  "rootfi_created_at": "2024-01-22T05:07:31.465Z",
  "rootfi_updated_at": "2024-01-22T05:07:31.000Z",
  "rootfi_company_id": 1089,
  "platform_id": "pay_shopify_001",
  "type": "payment",
  "order_id": "ord_shopify_001",
  "contact_id": "cus_001",
  "currency_id": "USD",
  "amount": 97.19,
  "status": "completed",
  "payment_method_type": "card",
  "gateway": "shopify_payments",
  "gateway_transaction_id": "gid://shopify/Transaction/12345",
  "description": "Payment for order ORD-2024-001",
  "created_at": "2024-01-22T05:07:31.465Z",
  "updated_at": "2024-01-22T05:07:31.000Z"
}

​
Refund Transaction Example

Refund Transaction Response
{
  "rootfi_id": 8002,
  "rootfi_created_at": "2024-01-23T10:15:00.000Z",
  "rootfi_updated_at": "2024-01-23T10:15:00.000Z",
  "rootfi_company_id": 1089,
  "platform_id": "ref_shopify_001",
  "type": "refund",
  "order_id": "ord_shopify_001",
  "contact_id": "cus_001",
  "original_transaction_id": "8001",
  "currency_id": "USD",
  "amount": 50.00,
  "status": "completed",
  "payment_method_type": "card",
  "gateway": "shopify_payments",
  "reason": "customer_request",
  "description": "Partial refund - customer return",
  "created_at": "2024-01-23T10:15:00.000Z",
  "updated_at": "2024-01-23T10:15:00.000Z"
}

​
Chargeback Transaction Example

Chargeback Transaction Response
{
  "rootfi_id": 8003,
  "rootfi_created_at": "2024-01-25T14:30:00.000Z",
  "rootfi_updated_at": "2024-01-25T14:30:00.000Z",
  "rootfi_company_id": 1089,
  "platform_id": "chg_shopify_001",
  "type": "chargeback",
  "order_id": "ord_shopify_002",
  "contact_id": "cus_002",
  "original_transaction_id": "8004",
  "currency_id": "USD",
  "amount": 149.99,
  "status": "completed",
  "payment_method_type": "card",
  "gateway": "shopify_payments",
  "reason": "fraud",
  "description": "Chargeback - disputed transaction",
  "created_at": "2024-01-25T14:30:00.000Z",
  "updated_at": "2024-01-25T14:30:00.000Z"
}