Transactions' Lifecycle

This guide explains how financial transactions flow through Connect Financial, from the moment a card is swiped or a bank transfer is initiated, to final settlement. Whether you're building a wallet app, a financial dashboard, or automating reconciliation, this guide will help you understand exactly how to track and display transaction data.

---

Table of Contents

1. Overview
2. Core Concepts
3. Transaction Domains
4. Card Transaction Flows
5. Bank Transaction Flows
6. Crypto Transaction Flows
7. Internal Transfer Flows
8. Webhook Events Reference

---

1. Overview

Overview

Connect Financial's transaction system tracks all financial movements with:

• Consistency: Same model across cards, bank transfers, and crypto
• Traceability: Every external event creates an immutable record
• Grouping: Related events share a parent*TransactionId for easy correlation
• Dual Linking: Wallet transactions include both the specific event ID and a grouping ID

Why Does This Matter for Your Integration?

Benefit	What It Means for You
Instant Grouping	Group all wallet transactions from a single card swipe with one filter (parentCardTransactionId)
Zero Extra API Calls	Grouping IDs are included in every response, hence no need to fetch additional data
Consistent Patterns	Same code patterns work for cards, bank, and crypto

About the Examples in This Guide

1. The examples throughout this guide use human-readable IDs like tx-debit-001 and ct-child-1 instead of actual UUIDs (e.g., 550e8400-e29b-41d4-a716-446655440000) to make the flows easier to follow.

2. Tables in this guide show only the most relevant columns for understanding each flow. Actual API responses include additional fields.

3. Refer to the API Reference for full endpoint schemas, all available fields, and exact response formats.

---

2. Core Concepts

2.1 Transaction Lifecycle & Events

A single financial action (like swiping a card) creates multiple events over its lifecycle:

Card Swipe at Coffee Shop ($50)
       │
       ├──► Event 1: Authorization (hold placed)
       │
       ├──► Event 2: Capture (merchant settles)
       │
       └──► [Optional] Event 3: Reversal (if voided)

Key Points:

• Each event is a separate transaction record with full details (type, status, amount)
• Related events share a common parentCardTransactionId for easy grouping
• Use parentCardTransactionId, parentBankTransactionId, or parentCryptoTransactionId to group related events
• Events are immutable. New activity creates new records, never updates

2.2 Two Types of Records

Connect Financial provides two ways to view transaction data:

Record Type	Purpose	When to Use
Domain Transactions	Card/Bank/Crypto-specific details	When you need merchant info, bank network, etc.
Wallet Transactions	Balance movements	When you need to track how balances change

Example: A $50 card authorization creates:

• 1 Card Transaction - Contains card ID, merchant, authorization code
• 2 Wallet Transactions - DEBIT from AVAILABLE, CREDIT to RESERVED

2.3 Grouping Transactions

Every wallet transaction includes parent*TransactionId fields that let you group related events:

{
  "id": "tx-001",
  "cardTransactionId": "ct-001",
  "parentCardTransactionId": "ct-group-001",
  "bankTransactionId": null,
  "parentBankTransactionId": null,
  "cryptoTransactionId": null,
  "parentCryptoTransactionId": null,
  "walletId": "wallet-123",
  "purpose": "DEBIT_CARD_HOLD",
  "operation": "DEBIT",
  "balanceType": "AVAILABLE",
  "amount": "50.00",
  "asset": "USD",
  "status": "COMPLETED",
  "createdAt": "2026-01-15T14:30:00Z"
}

How to use grouping:

// Group all wallet transactions from a single card swipe
const grouped = transactions.filter(tx => 
  tx.parentCardTransactionId === 'ct-group-001'
);
// Returns: authorization entries + capture entries + any reversals

Field	Use Case
cardTransactionId	Link to the specific card event
parentCardTransactionId	Group all entries from the same card swipe
bankTransactionId	Link to the specific bank event
parentBankTransactionId	Group all entries from the same bank transfer
cryptoTransactionId	Link to the specific crypto event
parentCryptoTransactionId	Group all entries from the same crypto transfer

This eliminates N+1 queries - you can group without additional API calls.

---

3. Transaction Domains

3.1 Card Transactions

What it tracks: Debit and credit card activity (authorizations, captures, refunds, reversals)

Fields returned by GET /v1/cards/transactions?cardId=X:

Field	Description
id	Unique identifier for this event
parentCardTransactionId	Use this to group related events together
cardId	The card involved
type	PRE_AUTHORIZATION, PRE_AUTH_COMPLETION, REVERSAL_ADVICE, etc.
operation	CREDIT or DEBIT
amount	Transaction amount
status	COMPLETED, FAILED, PENDING, CANCELLED

Card Transaction Types:

Type	Description	Triggered By
PRE_AUTHORIZATION	Hold placed on card	Swiping card at terminal
PRE_AUTH_COMPLETION	Hold converted to final charge	Merchant settlement
REVERSAL_ADVICE	Hold released or charge reversed	Merchant void/refund
ONLINE_TRANSACTION	Direct charge (no prior hold)	Force-post transactions
CREDIT	Refund or credit to card	Returns, credits
BALANCE_INQUIRY	Balance check (no financial impact)	ATM balance check

3.2 Bank Transactions

What it tracks: ACH/Wire deposits and withdrawals

Fields:

Field	Description
id	Unique identifier for this event
parentBankTransactionId	Use this to group related events together
walletId	The wallet involved
type	DEPOSIT_INITIATED, DEPOSIT_SUCCESS, WITHDRAWAL_SUCCESS, etc.
operation	CREDIT or DEBIT
amount	Transaction amount
status	COMPLETED, FAILED, PENDING
bankNetwork	ACH or SWIFT

Bank Transaction Types:

Type	Description
DEPOSIT_INITIATED	Deposit received, pending clearing
DEPOSIT_SUCCESS	Deposit cleared successfully
DEPOSIT_FAILURE	Deposit failed (returned, rejected)
WITHDRAWAL_INITIATED	Withdrawal submitted
WITHDRAWAL_SUCCESS	Withdrawal completed
WITHDRAWAL_FAILURE	Withdrawal failed

3.3 Crypto Transactions

What it tracks: Cryptocurrency deposits and withdrawals

Fields:

Field	Description
id	Unique identifier for this event
parentCryptoTransactionId	Use this to group related events together
walletId	The wallet involved
type	DEPOSIT_INITIATED, DEPOSIT_SUCCESS, WITHDRAWAL_SUCCESS, etc.
operation	CREDIT or DEBIT
amount	Transaction amount
status	COMPLETED, FAILED, PENDING
address	On-chain address
txHash	Blockchain transaction hash

---

4. Card Transaction Flows

4.1 Simple Authorization to Capture ($50 Coffee)

Timeline:

• T+0: Customer swipes card at coffee shop
• T+2h: Merchant settles

Step 1: Authorization (Card Swiped)

When the card is swiped, you receive a webhook and can fetch transactions:

Webhook Received:

{
  "eventType": "CARD_TRANSACTION_PENDING",
  "data": {
    "cardId": "card-123",
    "cardTransactionId": "ct-001"
  }
}

Card Transaction (via GET /v1/cards/transactions/ct-001):

Field	Value
id	ct-001
parentCardTransactionId	ct-group-001
type	PRE_AUTHORIZATION
amount	50.00
operation	DEBIT
status	COMPLETED

Wallet Transactions (via GET /v1/transactions?parentCardTransactionId=ct-group-001):

id	cardTransactionId	parentCardTransactionId	purpose	operation	balanceType	amount
tx-001	ct-001	ct-group-001	DEBIT_CARD_HOLD	DEBIT	AVAILABLE	50.00
tx-002	ct-001	ct-group-001	DEBIT_CARD_HOLD	CREDIT	RESERVED	50.00

Balance Change:

• AVAILABLE: -$50.00
• RESERVED: +$50.00

---

Step 2: Capture (Merchant Settles)

When the merchant settles, you receive another webhook:

Webhook Received:

{
  "eventType": "CARD_TRANSACTION_COMPLETED",
  "data": {
    "cardId": "card-123",
    "cardTransactionId": "ct-002"
  }
}

New Card Transaction:

Field	Value
id	ct-002
parentCardTransactionId	ct-group-001
type	PRE_AUTH_COMPLETION
amount	50.00
operation	DEBIT
status	COMPLETED

Note: parentCardTransactionId is the same (ct-group-001) - this groups it with the original authorization.

Updated Wallet Transactions (filtering by parentCardTransactionId=ct-group-001 now returns 4 entries):

id	cardTransactionId	purpose	operation	balanceType	amount
tx-001	ct-001	DEBIT_CARD_HOLD	DEBIT	AVAILABLE	50.00
tx-002	ct-001	DEBIT_CARD_HOLD	CREDIT	RESERVED	50.00
tx-003	ct-002	DEBIT_CARD_CAPTURE	DEBIT	RESERVED	50.00
tx-004	ct-002	DEBIT_CARD_CAPTURE	CREDIT	COMMITTED	50.00

Final Balance Change:

• AVAILABLE: -$50.00
• COMMITTED: +$50.00 (funds captured, will be settled to merchant)

---

4.2 Reversal (Customer Cancels)

If the merchant voids the transaction before settlement, you receive:

Webhook Received:

{
  "eventType": "CARD_TRANSACTION_CANCELLED",
  "data": {
    "cardId": "card-123",
    "cardTransactionId": "ct-002"
  }
}

Card Transaction:

Field	Value
id	ct-002
parentCardTransactionId	ct-group-001
type	REVERSAL_ADVICE
amount	50.00
operation	CREDIT
status	COMPLETED

New Wallet Transactions:

id	cardTransactionId	purpose	operation	balanceType	amount
tx-003	ct-002	DEBIT_CARD_HOLD	DEBIT	RESERVED	50.00
tx-004	ct-002	DEBIT_CARD_HOLD	CREDIT	AVAILABLE	50.00

Final Balance: $0 change (funds fully returned to AVAILABLE)

---

4.3 Declined Authorization

When a card authorization is declined (insufficient funds, fraud, etc.):

Webhook Received:

{
  "eventType": "CARD_TRANSACTION_FAILED",
  "data": {
    "cardId": "card-123",
    "cardTransactionId": "ct-001"
  }
}

Card Transaction:

Field	Value
id	ct-001
parentCardTransactionId	ct-group-001
type	PRE_AUTHORIZATION
amount	500.00
operation	DEBIT
status	FAILED

Wallet Transactions: NONE - Declines have no balance impact

Balance: Unchanged

---

4.4 Refund

When a merchant refunds a completed purchase:

Webhook Received:

{
  "eventType": "CARD_TRANSACTION_COMPLETED",
  "data": {
    "cardId": "card-123",
    "cardTransactionId": "ct-001"
  }
}

Card Transaction:

Field	Value
id	ct-001
parentCardTransactionId	ct-group-002
type	CREDIT
amount	50.00
operation	CREDIT
status	COMPLETED

Note: Refunds create a new parentCardTransactionId since they are a separate transaction lifecycle.

Wallet Transactions:

id	cardTransactionId	parentCardTransactionId	purpose	operation	balanceType	amount
tx-001	ct-001	ct-group-002	DEBIT_CARD_REFUND	CREDIT	AVAILABLE	50.00

Note: New funds are entering the system.

Balance Change: AVAILABLE +$50.00

---

5. Bank Transaction Flows

5.1 Bank Deposit ($100)

Timeline:

• T+0: Funds received from external bank
• T+1-3 days: Funds cleared

Step 1: Deposit Pending

Webhook Received:

{
  "eventType": "BANK_DEPOSIT_TRANSACTION_PENDING",
  "data": {
    "walletId": "wallet-123",
    "bankTransactionId": "bt-001"
  }
}

Wallet Transactions (via GET /v1/transactions?parentBankTransactionId=bt-group-001):

id	bankTransactionId	parentBankTransactionId	purpose	operation	balanceType	amount
tx-001	bt-001	bt-group-001	BANK_DEPOSIT_INITIATED	CREDIT	PENDING	100.00

Balance Change: PENDING +$100.00

---

Step 2: Deposit Completed

Webhook Received:

{
  "eventType": "BANK_DEPOSIT_TRANSACTION_COMPLETED",
  "data": {
    "walletId": "wallet-123",
    "bankTransactionId": "bt-002"
  }
}

Updated Wallet Transactions (filtering by parentBankTransactionId=bt-group-001):

id	bankTransactionId	parentBankTransactionId	purpose	operation	balanceType	amount
tx-001	bt-001	bt-group-001	BANK_DEPOSIT_INITIATED	CREDIT	PENDING	100.00
tx-002	bt-002	bt-group-001	BANK_DEPOSIT_SUCCESS	DEBIT	PENDING	100.00
tx-003	bt-002	bt-group-001	BANK_DEPOSIT_SUCCESS	CREDIT	AVAILABLE	100.00

Final Balance Change: AVAILABLE +$100.00

---

5.2 Bank Withdrawal ($100, $2 fee)

Step 1: Withdrawal Initiated

Webhook Received:

{
  "eventType": "BANK_WITHDRAWAL_TRANSACTION_PENDING",
  "data": {
    "walletId": "wallet-123",
    "bankTransactionId": "bt-001"
  }
}

Wallet Transactions (via GET /v1/transactions?parentBankTransactionId=bt-group-001):

id	bankTransactionId	parentBankTransactionId	purpose	operation	balanceType	amount
tx-001	bt-001	bt-group-001	BANK_WITHDRAWAL_INITIATED	DEBIT	AVAILABLE	102.00
tx-002	bt-001	bt-group-001	BANK_WITHDRAWAL_INITIATED	CREDIT	RESERVED	102.00

Balance Change: AVAILABLE -$102.00, RESERVED +$102.00

---

Step 2: Withdrawal Completed

Webhook Received:

{
  "eventType": "BANK_WITHDRAWAL_TRANSACTION_COMPLETED",
  "data": {
    "walletId": "wallet-123",
    "bankTransactionId": "bt-002"
  }
}

Updated Wallet Transactions (filtering by parentBankTransactionId=bt-group-001):

id	bankTransactionId	parentBankTransactionId	purpose	operation	balanceType	amount
tx-001	bt-001	bt-group-001	BANK_WITHDRAWAL_INITIATED	DEBIT	AVAILABLE	102.00
tx-002	bt-001	bt-group-001	BANK_WITHDRAWAL_INITIATED	CREDIT	RESERVED	102.00
tx-003	bt-002	bt-group-001	BANK_WITHDRAWAL_SUCCESS	DEBIT	RESERVED	100.00
tx-004	bt-002	bt-group-001	WITHDRAWAL_FEE_REVENUE	DEBIT	RESERVED	2.00
tx-005	bt-002	bt-group-001	WITHDRAWAL_FEE_REVENUE	CREDIT	FEE_REVENUE	2.00

Final Balance Change: AVAILABLE -$102.00 (sent $100 + $2 fee)

---

6. Crypto Transaction Flows

6.1 Crypto Deposit (0.5 BTC)

Step 1: Deposit Detected

Webhook Received:

{
  "eventType": "CRYPTO_DEPOSIT_TRANSACTION_PENDING",
  "data": {
    "walletId": "wallet-123",
    "cryptoTransactionId": "crt-001"
  }
}

Wallet Transactions (via GET /v1/transactions?parentCryptoTransactionId=crt-group-001):

id	cryptoTransactionId	parentCryptoTransactionId	purpose	operation	balanceType	amount
tx-001	crt-001	crt-group-001	CRYPTO_DEPOSIT_INITIATED	CREDIT	PENDING	0.5

---

Step 2: Deposit Confirmed

Webhook Received:

{
  "eventType": "CRYPTO_DEPOSIT_TRANSACTION_COMPLETED",
  "data": {
    "walletId": "wallet-123",
    "cryptoTransactionId": "crt-002"
  }
}

Updated Wallet Transactions (filtering by parentCryptoTransactionId=crt-group-001):

id	cryptoTransactionId	parentCryptoTransactionId	purpose	operation	balanceType	amount
tx-001	crt-001	crt-group-001	CRYPTO_DEPOSIT_INITIATED	CREDIT	PENDING	0.5
tx-002	crt-002	crt-group-001	CRYPTO_DEPOSIT_SUCCESS	DEBIT	PENDING	0.5
tx-003	crt-002	crt-group-001	CRYPTO_DEPOSIT_SUCCESS	CREDIT	AVAILABLE	0.5

---

7. Internal Transfer Flows

7.1 Wallet-to-Wallet Transfer ($50)

Internal transfers affect wallet balances directly (no card/bank/crypto domain). Each wallet owner receives their own webhook with the transaction ID that affects their wallet.

Webhook 1: Source Wallet Owner (money leaving)

{
  "eventType": "INTERNAL_TRANSACTION_COMPLETED",
  "data": {
    "walletId": "source-wallet-123",
    "transactionId": "tx-debit-001"
  }
}

Webhook 2: Destination Wallet Owner (money arriving)

{
  "eventType": "INTERNAL_TRANSACTION_COMPLETED",
  "data": {
    "walletId": "destination-wallet-456",
    "transactionId": "tx-credit-002"
  }
}

Wallet Transactions:

id	parentTransactionId	walletId	purpose	operation	balanceType	amount
tx-debit-001	tx-parent-001	source-wallet-123	VIRTUAL_INTERNAL_TRANSFER	DEBIT	AVAILABLE	50.00
tx-credit-002	tx-parent-001	destination-wallet-456	VIRTUAL_INTERNAL_TRANSFER	CREDIT	AVAILABLE	50.00

Grouping: Use parentTransactionId to group the debit and credit entries together.

---

8. Webhook Events Reference

8.1 Card Transaction Events

Event	When Fired	Payload
CARD_TRANSACTION_PENDING	Authorization approved, hold placed	{ cardId, cardTransactionId }
CARD_TRANSACTION_COMPLETED	Transaction settled/captured	{ cardId, cardTransactionId }
CARD_TRANSACTION_FAILED	Authorization declined	{ cardId, cardTransactionId }
CARD_TRANSACTION_CANCELLED	Transaction reversed/voided	{ cardId, cardTransactionId }

8.2 Bank Transaction Events

Event	When Fired	Payload
BANK_DEPOSIT_TRANSACTION_PENDING	Deposit received, pending	{ walletId, bankTransactionId }
BANK_DEPOSIT_TRANSACTION_COMPLETED	Deposit cleared	{ walletId, bankTransactionId }
BANK_DEPOSIT_TRANSACTION_FAILED	Deposit failed/returned	{ walletId, bankTransactionId }
BANK_WITHDRAWAL_TRANSACTION_PENDING	Withdrawal initiated	{ walletId, bankTransactionId }
BANK_WITHDRAWAL_TRANSACTION_COMPLETED	Withdrawal completed	{ walletId, bankTransactionId }
BANK_WITHDRAWAL_TRANSACTION_FAILED	Withdrawal failed	{ walletId, bankTransactionId }

8.3 Crypto Transaction Events

Event	When Fired	Payload
CRYPTO_DEPOSIT_TRANSACTION_PENDING	Deposit detected on-chain	{ walletId, cryptoTransactionId }
CRYPTO_DEPOSIT_TRANSACTION_COMPLETED	Deposit confirmed	{ walletId, cryptoTransactionId }
CRYPTO_DEPOSIT_TRANSACTION_FAILED	Deposit failed	{ walletId, cryptoTransactionId }
CRYPTO_WITHDRAWAL_TRANSACTION_PENDING	Withdrawal initiated	{ walletId, cryptoTransactionId }
CRYPTO_WITHDRAWAL_TRANSACTION_COMPLETED	Withdrawal confirmed	{ walletId, cryptoTransactionId }
CRYPTO_WITHDRAWAL_TRANSACTION_FAILED	Withdrawal failed	{ walletId, cryptoTransactionId }

8.4 Internal Transfer Events

Event	When Fired	Payload	Notes
INTERNAL_TRANSACTION_COMPLETED	Transfer completed	{ walletId, transactionId }	2 webhooks sent - one per wallet

Important: Internal transfers send two separate webhooks:

• Source wallet owner receives webhook with debit transaction ID
• Destination wallet owner receives webhook with credit transaction ID