Virtual Card Events/History

ConnexPay offers a variety of ways to help you understand the status of the cards that you have issued through the Purchase API and Bridge UI. While webhook notifications can be sent to your endpoint to inform you of status changes in real-time (webhook documentation can be found here), you can make use of the Search Issued and Virtual Card History API calls to inquire about your card's activity. You may also check statuses and events through Bridge UI by selecting the "Transaction Data" tab on the Purchase Details page for your issued purchases.

The Search Issued Cards API is a request that will return results of all issued cards matching the submitted criteria (details are found here for your developers). Included in these results will be identifying information such as the IncomingTransactionCode and CardGUID for the issued cards as well as their current cardStatus. The possible statuses and descriptions are as follows:

CardStatus:	Description
Unactivated	Identifies a card that has been created but has not yet been activated. An unactivated card cannot be successfully authorized for transactions.
Active	Identifies a created card that is active for transaction authorizations.
Deactivated	Identifies a card that was previously activated and subsequently deactivated. A deactivated card cannot be successfully authorized for transactions.

📘
Cards with Delayed Activation will display with a status of "Active" as they have a 1.00 available credit limit to allow for a successful pre-authorization by the vendor.

To obtain more detailed information on an individual card, the Search Virtual Card History API will return all authorization and transaction events matching the CardGUID submitted in the inquiry (developer document is located here). Importantly, an event type and status will be passed in the returned details which also corresponds with the information you would see in the Bridge UI. The below table lists these event types and statuses along with a description to understand the result (* events indicate transactions that will appear on your Daily Accounting File). Available webhook notifications are listed as well for aiding in any comparisons.

Event Types and Statuses:

Bridge Type	Bridge Status	Description • Equivalent Webhook
authorization	PENDING	A card authorization attempt has been approved. • purchase.card.auth.approved
authorization	DECLINED	A card authorization attempt has been declined. • purchase.card.auth.declined
authorization.clearing	COMPLETION	A settlement for fully processing a transaction on a card has been received. • purchase.card.auth.settled
authorization.clearing.chargeback	COMPLETION	A chargeback of a transaction previously settled has been initiated successfully.
authorization.clearing.chargeback	DECLINED	A chargeback of a transaction previously settled has been initiated unsuccessfully.
authorization.clearing.chargeback.completed	COMPLETION	A chargeback previously initiated has been accepted (the dispute has been won).
authorization.clearing.chargeback.completed	DECLINED	A chargeback previously initiated has been declined (the dispute has been lost).
authorization.clearing.chargeback.reversal	CLEARED	A previously accepted chargeback has been reversed.
authorization.reversal	CLEARED	A previously approved authorization has been voided by the supplier prior to completing the settlement process. • purchase.card.auth.reversal.settled
authorization.reversal.issuerexpiration	CLEARED	A previously approved card authorization has expired due to no settlement or reversal being received. • purchase.card.auth.reversal.issuerexpiration
refund.authorization	DECLINED	An attempt to return funds to a card after settlement occurred has been rejected. • purchase.card.return.auth.declined
refund.authorization	PENDING	An attempt to return funds to a card after settlement occurred has been approved but not yet completed. • purchase.card.return.auth.approved
refund.authorization.clearing	COMPLETION	An attempt to return funds to a card after settlement occurred has been approved and completed. • purchase.card.return.auth.settled
refund.authorization.reversal	CLEARED	The approval of an attempt to return funds to a card after settlement occurred has been reversed. • purchase.card.return.auth.reversal.settled

Purchases Event Flow

The following illustration helps show the flow of possible events (and their webhook notifications)that may occur during the lifecycle of a transaction on an issued purchase card.

Purchase Returns Event Flow

The following illustration helps show the flow of possible events (and their webhook notifications) that may occur during the lifecycle of a returned transaction on an issued purchase card.