You are here: CashBox1800APIGuide > The Transaction Object

18  The Transaction Object

The Transaction object encapsulates information about a financial transaction processed through CashBox. In addition to standard transaction content, such as customer information (Account), payment information (PaymentMethod), line items (TransactionItem), and amount, this object contains a rich set of attributes that support CashBox services.

A Transaction object might represent a financial transaction conducted through CashBox for recurring or one-time billing, or one conducted outside of CashBox, but reported to Vindicia for chargeback dispute through ChargeGuard. Please note that Refund objects, rather than Transaction objects encapsulate information on refunds to your customers.

CashBox processes Transaction objects with your payment processor and updates their status during the process. The Transaction object includes an array of TransactionStatus subobjects that form a log of statuses through the Transaction processing sequence.

When migrating a Transaction to CashBox, be certain to include the latest or final status information within the Transaction object (such as the reason code returned by your payment processor). The status cycle of a Transaction object and the reason codes will vary, depending on the payment method and your processor.

A Transaction object might also represent a potential, rather than a completed, financial transaction. For example, you may score a Transaction and screen it for fraud risk before moving funds through your payment processor. (For more information on risk screening, see Chapter 14: Common ChargeGuard Programming Tasks in the CashBox Programming Guide.) If the scoring result reflects a high fraud probability, you might decide to abandon the Transaction, in which case the corresponding Transaction object remains in CashBox in the New status, which means that it was never processed.

When Vindicia downloads chargebacks from your payment processor for ChargeGuard, it matches them to your transactions in its database. If you have conducted one of those transactions outside of Vindicia but have not yet migrated it, CashBox creates a stub Transaction object in its database with the Transaction information in the chargeback that was downloaded. After you’ve reported that transaction to CashBox, the object is populated with the remaining information.

The following table lists and describes cases in which a Transaction object should be used.


The "Transaction Types" listed in this table are not formal types, but simply general classifications.


Table 18-1: Uses for the Transaction Object

Transaction Type


Initiated By

Transaction API Call


Transactions generated by a billing system other than CashBox, that have been migrated into CashBox by either the AutoBill.migrate or Transaction.migrate calls. Once imported, these Transactions will behave as if they were Recurring/Real-time Transactions generated within CashBox.

You, the merchant



Real-time (one-time)

A one-time purchase by a customer. CashBox authorizes this transaction with your payment processor in real time in response to your call. Depending on the call, the transaction may be captured with the payment processor later in batch mode. A captured transaction means that monies will be exchanged. This type of transaction goes through status changes until it is eventually captured.

You, the merchant




Recurring billing

Periodic transactions generated by CashBox for an instance of an AutoBill object. These are recurring transactions for a customer’s subscription, with the frequency, amount, and other content determined by the Product and BillingPlan objects in the AutoBill object. To create an AutoBill instance for a customer’s subscription, either make an API call, or create the instance on the CashBox Portal. CashBox captures these transactions in batch mode. The status of the entitlements offered by the corresponding AutoBill object depends on whether the transaction is captured successfully.


None. An active AutoBill object must exist.


A transaction conducted outside of CashBox, and reported to Vindicia for chargeback dispute. CashBox does not process this transaction with a payment processor, nor does the transaction go through changes in status.

You, the merchant



A transaction with minimal data. If you are a ChargeGuard customer, Vindicia downloads your chargebacks from your payment processor and matches them to their corresponding Transactions in the Vindicia database to capture all information available for chargeback disputes.

If the original transaction is not in the database (was conducted outside of CashBox but not yet migrated), CashBox creates a stub Transaction object that contains the minimal data obtained from the chargeback, and stores the object in the database.

Once you have migrated the transaction, CashBox will enter the missing details.

Indirectly by you, the merchant



A transaction to validate a payment method. When you make an API call or perform a task on the CashBox Portal to validate a payment method, CashBox generates a Transaction that uses that payment method for an amount of one currency unit (US$1 if the payment method specifies USD as the currency), and authorizes it with your payment processor.

If the Transaction is authorized, the payment method is considered valid, and the transaction status becomes AuthorizedForValidation; if not, the status is Cancelled.

Not all payment methods may be validated this way. (See Section 11: The PaymentMethod Object for details.) Because CashBox only authorizes such a transaction with your processor but never captures it, the customer is not charged for the transaction.



When creating and processing a Transaction object through CashBox, reporting it to Vindicia for ChargeGuard, or scoring it for risk screening, be sure to include all related information. The more detail you provide, the more effective Vindicia will be in disputing chargebacks on your behalf should they occur.