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 hold for $1 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 their card is authorized for $100. Once the cardholder completes their purchase, the $100 authorization is adjusted to $45 and 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.
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 are set by merchants, and can vary across different merchants.
Reversals are used when an authorization needs to be canceled before a clearing event occurs. Reversals typically occur in the following scenarios:
- An item is out of stock
- The cardholder cancels their order before a clearing event occurs
- The authorization is no longer valid
Reversals can be done for the full amount of an authorization, or a partial amount.
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 to reverse a purchase, but a transaction 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