Card Events and Transactions are the two main elements involved in the lifecycle of a card payment on the Treasury Prime platform. Card Events are dispatched via webhook callback to provide notification that a specific type of message was received from the card network. In response to these messages, Treasury Prime also creates Transactions on the related account, which impacts the current and available balance.
networkdata
field. The networkdata
field is processor specific and contains the information received from the network for the event. For messages processed by Marqeta, more detailed information on fields present in a network message can be found in their documentation.
card_event.create
webhook firing. Likewise, if a Card Event is updated, the card_event.update
webhook is triggered. In both cases, a standard webhook response will be provided containing the id
of the Card Event object, along with a url
value to retrieve the object.
status
field which represents the current status of the object. The potential statuses are listed below:
Status | Description |
---|---|
pending | Actionable card events such as auth-request and refund-auth-request are initialized with a status of pending , and will eventually change to a status of approved or denied as the event is decisioned. |
error | An internal or other error has been encountered. |
approved | The card event has been approved. |
denied | The card event has been denied. |
timeout | A timeout status can occur when there is a delay in response to a request from the card network. In these instances, the card network will decline the transaction, and the status of the of the card event will be updated to reflect this case. |
received | This is an informational update to acknowledge receipt. There is no action to be taken. As the status field can change over time, you may see instances where a card event in status received later changes to denied or another status type. |
auth-request
auth-capture
auth-reversal
incremental-auth-request
refund-auth-request
refund
refund-auth-reversal
auth-standin
force-capture
auth-clear-request
auth-clear-adjustment
auth-clear-reversal
balance-inquiry-request
chargeback-request
chargeback-reversal
account-verification-request
auth-request
events (commonly known as authorizations) are by far the most common type of card event. This request seeks to validate that the account in question has sufficient funds to complete the transaction. Assuming the funds are available, a successful response is sent and a hold is created to ensure those funds remain available to complete the transaction.
If using the Card Auth Loop Endpoint to manage whether an auth-request
is accepted or rejected, you will receive a webhook callback to the url
provided in the Card Auth Loop Endpoint when an auth-request
occurs.
auth-request
for $25, and Treasury Prime responds with an approved amount of $10, and a hold
is created in that amount. The merchant receives a response informing them that the account only has $10 available, and an auth-capture
is dispatched for that amount. The initial $25 hold is then released, the available $10 is debited from the users account, and a new hold is created for the remaining authorized amount of $15. The final $15 hold will remain in place until the merchant clears it or the authorization expires (typically within 9 days).
Object | Type | Amount |
---|---|---|
Card Event | auth-request | 25 |
Transaction | hold | -10 |
Card Event | auth-capture | 10 |
Transaction | hold_release | 25 |
Transaction | withdrawal | -10 |
Transaction | hold | -15 |
Transaction | hold_release | 15 |
auth-capture
(commonly called a capture) occurs when a merchant verifies that a transaction is complete and requests that the funds be transferred. In many situations, this happens immediately after the transaction completes; however, depending on the merchant, it may take a number of days for a capture event to occur after the initial authorization.
Once the auth-capture
event is received, a hold-release
is issued in the amount of the initial authorization (releasing the funds for transfer), and a withdrawal
is then created to move the funds out of the users account.
Object | Type | Amount |
---|---|---|
Card Event | auth-request | 20 |
Transaction | hold | -20 |
Card Event | auth-capture | 20 |
Transaction | hold_release | 20 |
Transaction | withdrawal | -20 |
auth-request
for $100, which is approved, and a $100 hold
is created. The cardholder proceeds to pump $50 worth of gas and completes the transaction. At this point, the AFD sends an auth-capture
for $50. The initial $100 hold is released, $50 is debited from the users account, and a new hold is created for the remaining authorized amount of $50. The final $50 hold will remain in place until the merchant clears it or the authorization expires (typically within 9 days).
Object | Type | Amount |
---|---|---|
Card Event | auth-request | 100 |
Transaction | hold | -100 |
Card Event | auth-capture | 50 |
Transaction | hold_release | 100 |
Transaction | withdrawal | -50 |
Transaction | hold | -50 |
Transaction | hold_release | 50 |
auth-request
is sent, and later, a higher-value auth-capture
is sent for the total cost of the fuel purchased. This can lead to unexpected consequences, including overdrafts.
{% alert severity=“warning” %} Note: One way to manage this scenario is to use the Card Auth Loop Endpoint to review auth-requests
from AFDs (merchant code: 5542) and apply logic to determine whether to accept or reject the transaction based on the available balance for the account at that time. {% /alert %}
auth-request
is sent for $1, which is approved. They proceed to pump $50 worth of gas, and complete the transaction. At this point, the gas station, which needs to collect $50 but has only authorized payment for $1, will submit an auth-capture
which instructs the full amount ($50) to be paid regardless of the initial authorization amount.
Object | Type | Amount |
---|---|---|
Card Event | auth-request | 1 |
Transaction | hold | -1 |
Card Event | auth-capture | 50 |
Transaction | hold_release | 1 |
Transaction | withdrawal | -50 |
auth-reversal
is used to cancel or reverse an authorization before the funds have been captured.
auth-request
being sent. The customer then changes their mind and requests to cancel the transaction. The merchant cancels the transaction and an auth-reversal
is sent to ensure any funds being held are released.
Object | Type | Amount |
---|---|---|
Card Event | auth-request | 25 |
Card Event | auth-reversal | 25 |
auth-reversal
submitted before the auth-request
has been approved and a hold has been created.
auth-reversal
submitted after the auth-request
has been approved and a hold has been created.
Object | Type | Amount |
---|---|---|
Card Event | auth-request | 25 |
Transaction | hold | -25 |
Transaction | hold_release | 25 |
Card Event | auth-reversal | 25 |
auth-request
; this is where the incremental-auth-request
comes in. This request seeks to verify that the user has sufficient funds to cover the additional amount of the transaction, and if they do, results in both a hold-release
for the original amount and a hold
being created for the new total amount of the authorization.
auth-request
is submitted for $10 (the total amount of the bill), later an incremental-auth-request
is sent to add the value of the tip ($5) to the total amount of the authorization before finally submitting an auth-capture
to secure the final amount of the bill ($15).
Object | Type | Amount |
---|---|---|
Card Event | auth-request | 10 |
Transaction | hold | -10 |
Card Event | incremental-auth-request | 5 |
Transaction | hold_release | 10 |
Transaction | hold | -15 |
Card Event | auth-capture | 15 |
Transaction | hold_release | 15 |
Transaction | withdrawal | -15 |
refund-auth-request
is sent when a merchant wishes to verify that an account is available to receive a refund prior to sending the funds.
If using the Card Auth Loop Endpoint, a webhook callback will be triggered in response to this event, allowing you to approve or deny the request.
Object | Type | Amount |
---|---|---|
Card Event | refund-auth-request | 25 |
Card Event | refund | 25 |
Transaction | deposit | 25 |
Object | Type | Amount |
---|---|---|
Card Event | refund | 25 |
Transaction | deposit | 25 |
refund-auth-request
Object | Type | Amount |
---|---|---|
Card Event | refund-auth-request | 25 |
Card Event | refund-auth-reversal | 25 |
auth-standin
card event dispatched.
The initial auth-standin
event replaces the normal auth-request
event seen in most circumstances and is generally followed by a force-capture
event instead of an auth-capture
.
Note that as the authorization has already been approved, auth-standin
events do not trigger the webhook callback for the Card Auth Loop Endpoint, and you will not be able to decline the authorization.
Object | Type | Amount |
---|---|---|
Card Event | auth-standin | 25 |
Transaction | hold | -25 |
Card Event | force-capture | 25 |
Transaction | hold_release | 25 |
Transaction | withdrawal | -25 |
force-capture
is used when a valid authorization for the order is unavailable, but the order has been fulfilled and funds need to be transferred. This type of capture generally relies on a prior authorization for a lower amount than the capture to complete the transaction.
In rare occasions, the force capture may not be linked to the initial auth request by trace_id due to differing details/identifiers provided by the network.
force-capture
to secure the funds. Note the gap between the initial auth-request
and the auth-reversal
, as this delay in capturing funds is often the cause of the auth-reversal
being issued.
Date | Object | Type | Amount |
---|---|---|---|
2022-04-19 | Card Event | auth-request | 25 |
2022-04-19 | Transaction | hold | -25 |
2022-04-28 | Card Event | auth-reversal | 25 |
2022-04-28 | Transaction | hold_release | 25 |
2022-05-10 | Card Event | force-capture | 25 |
2022-05-10 | Transaction | withdrawal | -25 |
auth-request
and instead just issues a force-capture
for the full amount. This scenario is often seen at gas stations.
Date | Object | Type | Amount |
---|---|---|---|
2022-04-19 | Card Event | force-capture | 25 |
2022-05-10 | Transaction | withdrawal | -25 |
auth-clear-request
is essentially a combination of an auth-request
and an auth-capture
rolled into a single event. Theses single-message transactions are commonly seen with PIN debits and ATM withdrawals.
When an auth-clear-request
is received, the account is immediately debited for the full amount of the transaction with no prior hold
being placed on the funds.
Date | Object | Type | Amount |
---|---|---|---|
2022-04-19 | Card Event | auth-clear-request | 25 |
2022-04-19 | Transaction | withdrawal | -25 |
auth-clear-request
by the specified amount. This scenario, while somewhat rare, can occur in instances where a merchant issues an auth-clear-request
but the cardholder does not have enough funds in their account to cover the transaction. The most common outcome in this scenario is that a withdrawal will be made for the available balance on the cardholders account. The merchant will then complete the transaction and issue an adjustment for the difference between the final captured amount and the initial auth-clear-request
.
auth-clear-request
in the amount of $50, but upon receipt, it is determined that the user only has $25 available in their account. The $25 is captured and the merchant is notified, at which point the transaction is completed, but only in the amount of $20. So, the merchant then issues an auth-clear-adjustment
for the $5 difference, which is ultimately credited back to the users account.
Object | Type | Amount |
---|---|---|
Card Event | auth-clear-request | 50 |
Transaction | withdrawal | -25 |
Card Event | auth-clear-adjustment | 5 |
Transaction | deposit | 5 |
auth-clear-request
Object | Type | Amount |
---|---|---|
Card Event | auth-clear-request | 25 |
Transaction | withdrawal | -25 |
Card Event | auth-clear-reversal | 25 |
Transaction | deposit | 25 |
Object | Type | Amount |
---|---|---|
Card Event | balance-inquiry-request | 0 |
Object | Type | Amount |
---|---|---|
Card Event | auth-request | 25 |
Transaction | hold | -25 |
Card Event | auth-capture | 25 |
Transaction | hold_release | 25 |
Transaction | withdrawal | -25 |
Card Event | chargeback-request | 25 |
Transaction | deposit | 25 |
chargeback-request
.
Object | Type | Amount |
---|---|---|
Card Event | chargeback-request | 25 |
Card Event | chargeback-reversal | -25 |
account-verification-request
authorizes an account without placing a hold on funds.
Object | Type | Amount |
---|---|---|
Card Event | account-verification-request | 0 |