@cfxlabsinc/b2b-services
    Preparing search index...

    Type Alias Transaction

    type Transaction = {
        accountId: string | null;
        accountName: string | null;
        amount: BigNumber;
        bankId?: BankId;
        bankName?: string | null;
        bankTransactionId?: string;
        card?: {
            cardholderFirstName?: string;
            cardholderLastName?: string;
            id: string;
            last4?: string;
            merchantName?: string;
            transactionType?: "AUTHORIZATION" | "REVERSAL" | "ADJUSTMENT";
        };
        category: | "DEPOSIT"
        | "MANUAL_MINT"
        | "WITHDRAWAL"
        | "SWAP"
        | "TRANSFER"
        | "NETWORK_TRANSFER"
        | "FEE_TRANSFER"
        | "REDEMPTION"
        | "CARD"
        | "ESCROW_TRANSFER"
        | "REWARD"
        | "BLOCKCHAIN_DEPOSIT";
        counterpartyName: string
        | null;
        createdAt: Date;
        currency: string;
        customerName: string | null;
        description: string | null;
        deviceLocation?: { lat: number; long: number };
        entityEmail: string | null;
        entityId: string;
        entityName: string | null;
        entityType: "IDENTITY" | "ORGANIZATION" | null;
        failureReason: string | null;
        fees?: BigNumber;
        id: string;
        key: string;
        method:
            | "DEPOSIT_BLOCKCHAIN"
            | "DEPOSIT_DIRECT"
            | "DEPOSIT_US_BANK_ACH"
            | "DEPOSIT_ACH_CREDIT"
            | "DEPOSIT_RTP"
            | "DEPOSIT_US_CASH"
            | "DEPOSIT_US_WIRE"
            | "DEPOSIT_SWIFT_WIRE"
            | "REDEMPTION"
            | "SWAP"
            | "FEE_TRANSFER"
            | "TRANSFER"
            | "TRANSFER_NETWORK"
            | "WITHDRAW_AF_BANK"
            | "WITHDRAW_AF_MOMO"
            | "WITHDRAW_MX_SPEI"
            | "WITHDRAW_SWIFT_WIRE"
            | "WITHDRAW_US_BANK_ACH"
            | "WITHDRAW_US_INSTANT"
            | "WITHDRAW_ACH_PULL"
            | "WITHDRAW_US_WIRE_DRAWDOWN"
            | "WITHDRAW_US_WIRE"
            | "WITHDRAW_BLOCKCHAIN"
            | "VIRTUAL_CARD"
            | "PHYSICAL_CARD"
            | "ESCROW_TRANSFER"
            | "REWARD";
        otherWallet?: { address: Address; customer: { id: string; name: string } };
        paymentInstrumentId?: string;
        postBalance?: BigNumber;
        preBalance?: BigNumber;
        productQuoteId?: string;
        signature: string | null;
        sourceAmount?: BigNumber;
        sourceCurrency?: string;
        status: "PROCESSING" | "COMPLETED" | "FAILED" | "RETURNED";
        subType?: "RETURN" | "FEE" | "CLEARING";
        targetAmount?: BigNumber;
        targetCurrency?: string;
        type: "CREDIT" | "DEBIT";
        updatedAt: Date;
        walletAddress: Address | null;
    }
    Index
    accountId accountName amount bankId? bankName? bankTransactionId? card? category counterpartyName createdAt currency customerName description deviceLocation? entityEmail entityId entityName entityType failureReason fees? id key method otherWallet? paymentInstrumentId? postBalance? preBalance? productQuoteId? signature sourceAmount? sourceCurrency? status subType? targetAmount? targetCurrency? type updatedAt walletAddress
    accountId: string | null

    External ID (acc_…) of the ledger account at walletAddress. Null when the wallet has no ledger_account row. Stable identifier for downstream integrations; consumers should prefer this over walletAddress when exposing an account reference.

    accountName: string | null

    Display name of the ledger account at walletAddress. Null when the wallet has no ledger_account row.

    amount: BigNumber

    Currency amount, including fees, that were eventually debited from/credited to the account

    bankId?: BankId
    bankName?: string | null

    Display name of the bank at bankId, resolved in SQL via a LEFT JOIN to the bank reference table on its external_id (the slug carried in bankId). Null when the row has no bankId or the slug matches no bank row.

    bankTransactionId?: string
    card?: {
        cardholderFirstName?: string;
        cardholderLastName?: string;
        id: string;
        last4?: string;
        merchantName?: string;
        transactionType?: "AUTHORIZATION" | "REVERSAL" | "ADJUSTMENT";
    }

    Card for VIRTUAL_CARD, undefined otherwise.

    category:
        | "DEPOSIT"
        | "MANUAL_MINT"
        | "WITHDRAWAL"
        | "SWAP"
        | "TRANSFER"
        | "NETWORK_TRANSFER"
        | "FEE_TRANSFER"
        | "REDEMPTION"
        | "CARD"
        | "ESCROW_TRANSFER"
        | "REWARD"
        | "BLOCKCHAIN_DEPOSIT"

    Which of the twelve *_transaction_view arms produced this row. Most are single-member (SWAP, REWARD), because the split follows the views rather than any coarser idea of what a transaction is.

    The coarse grouping of Transaction.method consumers keep rebuilding by hand — isAsyncMoneyMovementMethod in the admin dashboard is a startsWith("WITHDRAW_") plus ten method === comparisons, which is this field spelled as string-sniffing. Branch on category; prefix tests on method are not a contract.

    counterpartyName: string | null

    The other account holder's display name relative to this row's audience.

    Null when:

    • the row is a system-level interaction (FEE debit, RETURN credit) — never expose CFX as a counterparty
    • the row's counterparty is the platform itself (DEPOSIT_DIRECT, REDEMPTION, DEPOSIT_SWIFT_WIRE pending)
    • the JOIN misses (orphaned PI, etc.)

    Consumers render the literal label (e.g. "Platform", "Fee", "Return {id}") by branching on method / subType.

    createdAt: Date
    currency: string

    ISO currency code

    customerName: string | null

    Display name of the customer (CFX customer) at customerId. Resolved in SQL from customer.name.

    description: string | null

    Fully-formatted English description for the to/from cell — already incorporates counterpartyName where applicable. Examples: "From John Doe", "To Platform", "{shortenedAddr} SOL", "Currency exchange", "Return {id}", "Fee", "Card payment", "Not available".

    Consumers render the cell as description ?? "Not available". Use counterpartyName (the bare name) when you need just the entity for avatars, logos, or branching — description is the rendered string.

    deviceLocation?: { lat: number; long: number }

    Approximate user device location (IP-derived) at the time the originating quote was created. Populated for deposits and withdrawals that captured a deviceLocation on the creating request; undefined for all other transaction types.

    entityEmail: string | null

    Email of the entity if it's an IDENTITY. Null for organizations and for unresolved entities.

    entityId: string
    entityName: string | null

    Display name of the entity (identity or organization) that owns this row, resolved in SQL via the existing identity/organization JOINs.

    Null only on orphaned-FK rows.

    entityType: "IDENTITY" | "ORGANIZATION" | null

    Discriminator for the entity at entityId — IDENTITY (a specific person), ORGANIZATION, or null when the entity isn't directly resolvable.

    failureReason: string | null

    Operator-entered reason recorded when a transaction was manually cancelled or failed (the latest FAILED / RETURNED / CANCELLED status transition's data.reason). Only deposit / withdrawal / ledger-transfer rails capture one; null for every other rail and for transitions with no reason.

    fees?: BigNumber

    Total fees taken, in sourceCurrency. Sourced from product_quote.total_fees. May be undefined for LEGACY product_quote rows (older transactions where fee breakdowns weren't recoverable).

    id: string

    Not necessarily unique, e.g. transfers will appear as credit and debit transactions with the same ID.

    key: string

    Unique row identity: concat_ws('-', id, type, subType) — id-type for a main leg (NULL subType) and id-type-FEE / id-type-CLEARING / etc. for a sub-row. Unlike Transaction.id this uniquely identifies a single read-model row — it matches the (id, type, subType) tuple get() leg-pins on and the admin-dashboard's transactionRowKey. Deliberately excludes createdAt: it is stable identity, not a cursor.

    method:
        | "DEPOSIT_BLOCKCHAIN"
        | "DEPOSIT_DIRECT"
        | "DEPOSIT_US_BANK_ACH"
        | "DEPOSIT_ACH_CREDIT"
        | "DEPOSIT_RTP"
        | "DEPOSIT_US_CASH"
        | "DEPOSIT_US_WIRE"
        | "DEPOSIT_SWIFT_WIRE"
        | "REDEMPTION"
        | "SWAP"
        | "FEE_TRANSFER"
        | "TRANSFER"
        | "TRANSFER_NETWORK"
        | "WITHDRAW_AF_BANK"
        | "WITHDRAW_AF_MOMO"
        | "WITHDRAW_MX_SPEI"
        | "WITHDRAW_SWIFT_WIRE"
        | "WITHDRAW_US_BANK_ACH"
        | "WITHDRAW_US_INSTANT"
        | "WITHDRAW_ACH_PULL"
        | "WITHDRAW_US_WIRE_DRAWDOWN"
        | "WITHDRAW_US_WIRE"
        | "WITHDRAW_BLOCKCHAIN"
        | "VIRTUAL_CARD"
        | "PHYSICAL_CARD"
        | "ESCROW_TRANSFER"
        | "REWARD"
    otherWallet?: { address: Address; customer: { id: string; name: string } }

    The secondary wallet for transaction

    • Transfer (debit): the wallet that is credited
    • Transfer (credit): the wallet that is debited
    paymentInstrumentId?: string

    Source payment instrument ID for DEPOSIT_* and target payment instrument ID for WITHDRAW_*. Undefined otherwise.

    postBalance?: BigNumber

    MOVEUSD token balance after the on-chain transaction (from solana_account_transaction).

    preBalance?: BigNumber

    MOVEUSD token balance before the on-chain transaction (from solana_account_transaction).

    productQuoteId?: string

    External id (pq_...) of the product_quote audit row that priced this transaction. Present for deposit/withdrawal/swap; undefined for card/transfer/blockchainDeposit/redemption/feeTransfer/manualMint.

    signature: string | null
    sourceAmount?: BigNumber

    Gross amount the originator put in, in sourceCurrency. Sourced from product_quote.source_amount. Undefined for non-quoted transaction kinds.

    sourceCurrency?: string
    status: "PROCESSING" | "COMPLETED" | "FAILED" | "RETURNED"
    subType?: "RETURN" | "FEE" | "CLEARING"
    targetAmount?: BigNumber

    Net amount the recipient gets, in targetCurrency. Sourced from product_quote.target_amount_after_fees. Undefined for non-quoted kinds.

    targetCurrency?: string
    type: "CREDIT" | "DEBIT"
    updatedAt: Date
    walletAddress: Address | null

    The primary wallet for transaction

    • Deposit: the wallet that is credited
    • Withdrawal, redemption: the wallet that is debited
    • Transfer (debit): the wallet that was debited
    • Transfer (credit): the wallet that was credited

    Null for off-chain transaction types that never touch a wallet (e.g. REWARD, which moves balance on the reward ledger, not on-chain).

    Settings
    Member Visibility

    On This Page
    Properties