Transaction

DefinitionCopied!

The Transaction entity is a core component of "The HIVE" platform, representing a single financial operation or movement of funds. It captures the essential details of each monetary transaction, ensuring traceability, security, and clarity.

Transaction scopeCopied!

Wallet Transactions: These transactions pertain to the ledger of a wallet. They track the inflow or outflow of funds, reflecting the wallet's activity and balance.
Passthrough Transactions: These are specialized child transactions designed to fund other parent transactions. Examples include funding international transfers or P2P transfers. They facilitate the seamless movement of funds from a payment method, such as a card or bank account, to fund a higher-level transaction.
Vault Transactions: These transactions can depict transfers from a wallet to a treasury vault, from a treasury vault to a wallet, or even between a treasury vault and an external bank. Their role is pivotal in adding or removing funds to/from the platform's economy.

Transaction statusCopied!

The state of a transaction is dynamic, often transitioning through various stages from its initiation to its culmination. Each status offers insights into the transaction's current phase, allowing for better management and oversight.

Status	Description
`CREATED`	The transaction has been initialized in the system, serving as the inception point.
`PROCESSING`	At this stage, the transaction is in the midst of processing, typically when a ledger transaction necessitates a payment action.
`PROCESSING_PAYMENT`	The funds for the transaction are being sourced from a payment method like a card and are currently under processing.
`COMPLETED`	A successful status indicating the effective transfer of funds.
`FAILED`	The transaction couldn't process, typically due to payment rejection, like a declined card transaction.
`ERROR`	A system glitch or anomaly that hindered the transaction's processing.
`CANCELED_USER`	The transaction was halted either by a customer or an agent via the Portal.
`CANCELED_SYSTEM`	An automated system rule resulted in the transaction's cancellation.
`VOIDED`	The transaction was nullified before the actual payment execution, ensuring no debit or credit on the payment method.
`PENDING`	The transactions is awaiting customer action, or waiting for funds to settle.
`MANUAL_REVIEW`	This status signifies that the transaction is undergoing a thorough review by Alviere's compliance and risk department.
`WAITING`	The transaction is on standby, often awaiting the availability of wallet balance funds or inputs from the corresponding prefunding vault.
`REJECTED`	After manual scrutiny, the transaction was declined by the risk and fraud department.

Transaction typeCopied!

Each transaction within "The HIVE" is categorized by a specific type, helping users and administrators understand the purpose and nature of a financial action. The following table provides a detailed breakdown of the available transaction types:

Transaction Type	Description	Wallet	Passthrough	Vault
`ACH_PRENOTE`	Zero-dollar test transaction that is sent through the Automated Clearing House (ACH) network. Its purpose is to verify the accuracy of account numbers and routing numbers before initiating actual transactions.	✓	-	✓
`ADJUSTMENT`	Transaction initiated by the Operations team to make modifications or corrections in the ledger of a wallet or vault. This action is undertaken to address discrepancies, errors, or to align the ledger with real-world financial activities, ensuring accurate record-keeping and system integrity.	✓	-	✓
`BANK_CREDIT`	Transaction type indicating the credit of funds to a wallet resulting from a direct deposit transfer.	✓	-	✓
`BANK_DEBIT`	Transaction type indicating the transfer of funds from a wallet to a bank account. This can be via bank transfer to a local Beneficiary or as a result of a direct debit from merchants.	✓	-	✓
`CARD_PASSTHROUGH`	Transaction type denoting the direct transfer of funds from a card payment method, bypassing the wallet ledger, to facilitate specific transactions, such as direct bill payments, third-party payments, or international transfers, without affecting the end user's wallet balance.	-	✓	✓
`CASH_PASSTHROUGH`	Transaction type denoting the direct transfer of funds from a cash deposit, bypassing the wallet ledger, to facilitate specific transactions, such as direct bill payments, third-party payments, or international transfers, without affecting the end user's wallet balance.	-	✓	✓
`BANK_PASSTHROUGH`	Transaction type denoting the direct transfer of funds from a bank payment method, bypassing the wallet ledger, to facilitate specific transactions, such as direct bill payments, third-party payments, or international transfers, without affecting the end user's wallet balance.	-	✓	✓
`BOOST`	Transaction type that functions as a discount mechanism during card authorizations. When applied, it enhances the available wallet balance for authorization purposes.	✓	-	✓
`CASH_LOADING`	Transaction type indicating the addition of funds into a wallet by depositing physical cash, often through retail partners, kiosks, or other physical cash handling facilities.	✓	-	✓
`CASHBACK`	Transaction that signifies a credit given to a wallet as a reward or incentive based on specific purchasing behaviors or promotions.	✓	-	✓
`CHARGEBACK`	Transaction initiated when a cardholder disputes a charge, resulting in the funds being debited from the payment processing account and returned to the cardholder.	✓	-	✓
`CARD_ISSUED_ADJUSTMENT`	Transaction type related to adjustments or corrections made specifically for transactions or balances associated with a card issued by the platform. This adjustment can be initiated due to various reasons, such as system errors, transaction discrepancies, mischarges, or other irregularities that need alignment to ensure accurate record-keeping and balance integrity for the cardholder's wallet.	✓	-	✓
`CARD_ISSUED_ATM_DEBIT`	Transaction that signifies a debit or withdrawal of funds from a cardholder's wallet specifically when the issued card is used at an ATM for cash withdrawal purposes.	✓	-	✓
`CARD_ISSUED_CREDIT`	Transaction that represents the crediting of funds to a wallet following an activity or adjustment related to a card issued by the platform. This could be due to reasons such as merchant refunds, or any other credits associated with the card's transactions.	✓	-	✓
`CARD_ISSUED_DEBIT`	Transaction that represents a debit from a cardholder's wallet when a purchase or payment is made using the issued card from our platform. This denotes the funds used for regular point-of-sale or online transactions.	✓	-	✓
`CARD_ISSUED_DISPUTE_CREDIT`	Transaction type representing a credit adjustment to a cardholder's wallet following the resolution of a dispute in their favor.	✓	-	✓
`CARD_ISSUED_DISPUTE_DEBIT`	Transaction type denoting a debit adjustment to a cardholder's wallet due to a dispute resolution that resulted in a chargeback or deduction.	✓	-	✓
`CARD_ISSUED_FEE`	Transaction representing a fee that originates externally and applies to a specific transaction conducted with a card issued by the platform.	✓	-	✓
`CARD_ISSUED_INITIAL`	Transaction indicating the initial balance added to cards issued by the platform. This type is specifically used for prepaid, prepaid non-reloadable, and gift cards, representing the fund amount that the card is initially loaded with when issued.	✓	-	✓
`CARD_ISSUED_OTC_DEBIT`	Transaction type pertains to instances when a cardholder utilizes their card with a human teller at a bank counter, typically to withdraw funds or conduct other card-related transactions.	✓	-	✓
`CARD_ISSUED_REISSUE`	Transaction that signifies the reissuance of a gift or prepaid card under the just-in-time funding model. It involves transferring the remaining balance from an expired card to a new one, ensuring continued card usage and balance availability even after the original card's expiration.	✓	-	✓
`CARD_ISSUED_RESET`	Transaction that represents the action of resetting the balance of prepaid cards or gift cards when such a card is deemed deleted or has expired. This is particularly relevant for programs operating under the "just in time" funding model, ensuring the funds are effectively managed and accounted for in such scenarios.	✓	-	✓
`CARD_ISSUED_TERMINAL_CREDIT`	Transaction type indicating the loading of cash into the wallet associated with a card via a terminal, utilizing networks like Visa ReadyLink and Mastercard Repower.	✓	-	✓
`CASHBACK`	Transaction that signifies a credit given to a wallet as a reward or incentive based on specific purchasing behaviors or promotions.	✓	-	✓
`CHECK_DEPOSIT`	Transaction type denoting the deposit of funds into a wallet through the submission and clearance of a digital check.	✓	-	✓
`CHECK_DEPOSIT_RETURN`	Transaction indicating the return of a deposited check, often due to reasons like insufficient funds or a suspected fraud.	✓	-	✓
`CHECK_DISBURSEMENT`	Transaction type representing the distribution of funds from a wallet or vault in the form of a physical or digital check issued to an end-user or another entity.	✓	-	✓
`EXTERNAL_CREDIT`	Transaction that denotes the credit of funds into a vault from an external financial source, augmenting the vault's balance.	-	-	✓
`EXTERNAL_DEBIT`	Transaction indicating the debit of funds from a vault, transferring them to an external financial destination, reducing the vault's balance.	-	-	✓
`INTERNAL_CREDIT`	Transaction type indicates the movement of funds internally between different vaults within the platform.	-	-	✓
`INTERNATIONAL_TRANSFER`	Transaction type indicating the movement of funds across borders, enabling your customers to send money to international Beneficiaries.	✓	-	✓
`LOAD_FUNDS`	Transaction that pulls funds from a specified payment method (such as a linked bank account or card) and credits them into a wallet within the platform. Typically used to add liquidity or top up a wallet balance.	✓	-	✓
`LOAD_PULLBACK`	Transaction initiated by the platform's fraud teams to pull funds from a specified payment method. This action is taken to cover and rectify a wallet's negative balance, ensuring account stability and mitigating potential financial discrepancies.	✓	-	✓
`NEGATIVE_LOSS`	Transaction type representing the write-off of a negative wallet balance that cannot be recovered, often due to account closures or unresolved fraudulent activities.	✓	-	✓
`PAYMENT`	Transaction type signifies a transaction associated with a merchant's payment processing program. It can either credit or debit funds to the main wallet, depending on the context.	✓	-	✓
`PREFUND`	Transaction type that signifies the reverse movement, where funds are credited back to the Master FBO vault from the Prefunding vault. In this case, the Prefunding vault is debited while the Master FBO vault is credited. This mechanism ensures flexibility and fluidity in managing balance funds, allowing for operational efficiency and ensuring that funds are readily available where needed within the platform.	-	-	✓
`RECOVERY`	Transaction that is implemented to reclaim funds from a wallet within the program due to fraudulent activities or suspicious transactions.	✓	-	✓
`REFUND`	Transaction type where funds are returned post-transaction, indicating that the initial transaction was processed, and the funds had been debited or credited, but are now being returned to the original source. This is different from a REVERSAL, where the transaction is nullified before any fund movement occurs outside of the platform.	✓	-	✓
`RETURN`	Transaction that signifies the reversal of a previous ACH transfer due to reasons such as insufficient funds, closed account, or other reject codes provided by the receiving bank.	✓	-	✓
`REFUND_PASSTHROUGH`	Transaction type where funds are returned through a payment method post-transaction. This is specifically for transactions where the initial transaction was processed using a passthrough mechanism, and now the funds are being sent back through the same payment method, essentially reverting the initial fund movement. This maintains the continuity and traceability of funds as they flow back to the original source via the passthrough method.	-	✓	✓
`REVERSAL`	Transaction type indicating the reversal of a previously initiated transaction before the funds have left the platform's economy. Unlike a REFUND where funds have been processed and returned post-transaction, in a REVERSAL, the transaction is nullified before any actual fund movement occurs outside of the platform.	✓	-	✓
`SERVICE_FEE`	Transaction that debits funds from a user's wallet and transfers them to the service fee treasury vault. This action is taken to cover a service fee that's charged to the end customer for using a specific service or product on the platform.	✓	-	✓
`SERVICE_FEE_REVERSAL`	Transaction that credits funds back into a user's wallet from the service fee treasury vault. This is initiated when a previously charged service fee is reversed or refunded to the end customer, typically due to an error, dispute, or promotional activity.	✓	-	✓
`TRANSIT_TRANSFER`	Transaction type that denotes an internal movement of funds from the Master FBO vault to the Prefunding vault. This action represents a debit from the Master FBO vault and a subsequent credit to the Prefunding vault. It is utilized to allocate funds that are in transit, ensuring the appropriate categorization and availability of resources within the platform's financial infrastructure.	-	-	✓
`TRANSFER`	A transaction type that denotes the movement of funds from a vault to a wallet, facilitating the funding or replenishing of an individual's or entity's balance from centralized treasury holdings.	✓	-	✓
`WALLET_TRANSFER`	Transaction type represents the movement of funds from one wallet to another within the same program. This function is similar to a peer-to-peer (p2p) payment, enabling users to transfer their funds seamlessly to another user's wallet without needing an external intermediary.	✓	-	✓
`WITHDRAW_FUNDS`	Transaction that pushes or debits funds from a wallet within the platform and transfers them to a specified payment method (like a bank account or card). This is commonly used to cash out or retrieve funds from a wallet.	✓	-	✓