Home / Issuing / Handle Transactions
Transaction Lifecycle
Note: See the TransactionEvent API Reference for a complete list of possible transaction events.
Transaction events occur when a payment card is used by an account holder online or in-store. These events are sent to Highnote based on logic set by the merchant and the merchant’s processor. This guide provides an overview of Highnote's transaction event lifecycle.
The most common transaction events include the following:
| Transaction event | Description | Example |
|---|---|---|
| Verification event | An initial check to confirm the payment method is valid | A temporary $1 hold is placed on the financial account to validate the payment method. |
| Authorization event with a separate clearing event | Reserves the amount on the cardholder's account to perform a separate clearing event | An authorization for $40 is placed on the account, and the amount is held but not yet transferred to ensure funds availability when the clearing event occurs. This type of event is common when a cardholder dines out and adds a tip on their card after the card has been authorized. |
| Authorization event with a combined clearing event | Reserves the amount on the cardholder's account and immediately clears the transaction to transfer the funds | The cardholder purchases groceries and the authorization and clearing events occur at the same time, removing the funds from the cardholder's account immediately. |
| Reversal event | An authorized transaction is canceled before a clearing event occurs | The cardholder makes an online purchase and immediately realizes they ordered the wrong size. They cancel the order and the merchant processes a reversal, releasing the hold on the cardholder's account before funds are transferred. |
| Clearing event | Funds are transferred from the cardholder's account | A cardholder purchases $45 worth of gas and a temporary authorization is put on the card for $1 to verify funds availability. Once the cardholder completes their purchase, the transaction clears for $45. |
| Refund | Returning funds to the cardholder's account after a transaction has been cleared and settled | A cardholder makes a purchase and later decides to return the item to the store. Once the item is returned, the merchant processes a refund to credit the cardholder's account for the purchase. |
The following graphic outlines the most common transaction events in the transaction event lifecycle:
Verification events are typically done to prevent fraud and validate a payment card. Validations are typically done in the following scenarios:
- A cardholder adds their payment card to a digital wallet
- A cardholder saves their payment card as a payment method online
- A cardholder adds their payment card to a Peer-to-Peer Payments app
Verifications may be declined for several reasons. Examples include, but are not limited to:
- Incorrect name or address provided
- Merchant Category Code (MCC) blocked for card or product
- Wrong zip code provided
When a verification is declined, Highnote provides a Response Code explaining why.
Authorization events are decisioned by Highnote based on your card product logic and may be approved or denied based on several factors.
Authorizations may reflect different requested and approved amounts. When an authorization is approved, the amount reflected on the Highnote ledger is the approved amount. These amounts are defined as follows:
- Requested amount: The amount of funds requested from the network for the transaction.
- Approved amount: The amount of funds approved and posted to the Highnote ledger for the transaction.
You can participate in the authorization flow using Collaborative Authorization. Collaborative authorization allows you to approve or decline the transaction before it reaches Highnote for decisioning.
Transactions can be approved for the following:
- The full amount of the transaction
- A partial amount of the transaction
- For special types of authorizations
When a transaction is approved, Highnote typically returns an APPROVED response code. For a full list of transaction response codes, see the TransactionEventResponseCode API Reference.
Declines occur for several reasons, including but not limited to:
- Insufficient funds in the account holder's financial account
- Incorrect PIN or CVV
- Expired payment card
When an authorization is declined, the merchant will receive a response code for the decline reason. These response codes are typically used by the merchant and displayed during the payment lifecycle. For a full list of transaction response codes, see the TransactionEventResponseCode API Reference.
In some scenarios, special types of authorizations may take place. The following table provides examples of special authorization types:
| Type | Description |
|---|---|
| Partial authorization | If the original authorization amount cannot be approved, Highnote may approve a partial amount. |
| Automated Fuel Dispenser (AFD) transactions | Automated fuel dispensers (AFDs) typically have an authorization amount defined by card product or network rules. |
| $0 authorization | Merchants may send an authorization for a zero dollar amount to validate card details. This authorization typically happens when a card is saved for future payments. |
When an authorization is approved, it acts as a hold for the authorized amount. Typically, funds on hold are displayed as "pending" in an application or website.
Note the following about pending authorizations:
- Expiration periods set by the merchant, card product logic, or network rules; with most authorizations expiring after seven days
- Some authorizations, like hotel stays or car rentals, may have longer expiration periods.
- When an authorization expires, the funds are automatically decreased on the account holder's authorization ledger and increased on their cash available ledger.
If you participate in authorization via Collaborative Authorization, Highnote responds to a transaction event with a pre-authorization to temporarily fund the requested authorization until your collaborative authorization response is received.
Note: Highnote does not have control over how reversal logic is implemented. Decisioning for reversals is set by the card network, and can vary across different merchants.
Reversals are used when a transaction needs to be canceled. Reversals can be done for the full amount of the transaction or a partial amount.
Reversals typically occur in the following scenarios:
- An item is out of stock
- A transaction is identified as fraud
- The cardholder cancels their order before a clearing event occurs
- The original authorization is no longer valid
- A duplicate transaction occurred
- Disputed transactions
- Merchant error
Reversals are determined by the card network. For reversals that occur after an authorization and clear transaction, we recommend handling these scenarios as refunds.
Once an authorization event is confirmed, a clearing event takes place to transfer the funds from the account holder's financial account to the merchant. When the funds are transferred, the account holder's authorization ledger is updated and the cash ledger is decreased.
Note the following about clearing events:
- Most clearing events are associated with an authorization event.
- If a clearing event is received without an authorization event, this is called a "forced post" and Highnote will monitor these clearing events to ensure fraud is not occurring.
Refunds occur when a merchant needs refunds a purchase that has already cleared. Refunds are typically sent in the following ways:
- The merchant sends a new authorization event with the refund amount provided as a credit
- The merchant sends a clearing event with no authorization for the amount to be refunded as a credit
- The merchant sends an authorization and clearing event for the amount to be refunded as a credit
Refer to the following guides to simulate transactions using the Highnote API:
- For all card products, except fleet: Simulate Transactions
- For fleet card products: Simulate Fleet Transactions