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

​
Transaction Attributes

PropertyTypeDescriptionRequiredExpandable
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
AUTHORIZEDTransaction has been authorized but not yet captured
CANCELEDTransaction was canceled
FAILEDTransaction failed to process
PAIDTransaction payment was successfully captured
PENDINGTransaction is being processed
REFUNDEDTransaction funds were returned or credited back
REQUIRES_ACTIONTransaction requires additional action before it can be completed
REVERSEDTransaction was reversed after completion
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=PAID

{
  "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": "PAID",
  "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": "REFUNDED",
  "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": "REFUNDED",
  "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"
}