Transaction Concept

A Transaction represents the primary record of money movement in SanctusPay’s payment platform. It indicates whether a particular flow of funds is a payment, a refund, or a chargeback, and contains the essential data needed to track, audit, and manage the lifecycle of that financial event.

Field Descriptions

Field	Type	Description
id	string	The unique identifier for the transaction (e.g., trx_01J5XCMDXCFXCAQ1BV8HVG6644). Use this value to retrieve, update, or reference the transaction in subsequent API calls.
type	string	The high-level category of transaction. See Transaction Types below.
status	string	Indicates the current state of the transaction in its lifecycle. See Transaction Status below.
order_amount	integer	The total order amount in the smallest currency unit (e.g., cents for USD). For example, $100.00 would be 10000.
order_currency	string	The three-letter ISO currency code (e.g., USD, EUR) representing the transaction’s currency.
amount_authorized	integer	The total authorized amount (in the smallest currency unit). This reflects how much was initially authorized—even if only part of it is ultimately captured.
amount_captured	integer	The cumulative sum of all captures that have been applied to this transaction. If partial captures occur, this value will increment until it reaches the total authorized amount.
amount_voided	integer	The total amount voided from the initial authorization. Voids typically occur before funds are captured, effectively canceling part or all of the authorization.
amount_refunded	integer	The total amount refunded back to the customer after funds are captured. For REFUND transactions, this value should match the order_amount if it’s a full refund.
external_id	string	A merchant-supplied reference (e.g., an order ID or UUID) that links this transaction to your internal systems.
updated_at	string	An ISO 8601–formatted timestamp (UTC) indicating when the transaction was last updated. For example, 2024-09-05T05:05:25Z.

Transaction Types

• PAYMENT: Standard transaction flow where a customer pays the merchant. Typically begins with authorization, followed by capture (partial or full).

• REFUND: The returning of funds to a customer for a previously captured payment. This transaction references the original payment and tracks the refunded amount.

• CHARGEBACK: Initiated by the cardholder’s bank due to a dispute or fraudulent activity. Funds previously captured may be reversed, pending further investigation or resolution.

Transaction Statuses

• AUTHORIZED: The transaction has been authorized. Funds are held but not captured. The hold is kept until you capture, void or it expires automatically.

• DECLINED: The authorization was rejected due to insufficient funds, fraud checks, or other reasons. The actual reason will be shown in the Operation.
• VOIDED: The authorization was canceled before funds were captured. No money moves in a void and the cardholder gets the authorized amount available immediately.

• PARTIAL_CAPTURED: Only a portion of the authorized amount was captured so far.

• CAPTURED: The entire authorized amount is captured. The money has left the cardholder's account and will be transferred to the Merchant.

• EXPIRED: The authorization window elapsed without capture or void, automatically releasing the hold on funds.