> ## Documentation Index
> Fetch the complete documentation index at: https://docs.treasuryprime.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Card Events
> 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.
The examples outlined for each Card Event type below are meant to be representative of common scenarios seen with card transactions, but do not represent every potential scenario you might encounter. As such, it is recommended that you place greater emphasis on understanding the common patterns encountered between Card Events and Transactions, and less on coding to accommodate these specific examples.
## Example Card Event object
```bash bash theme={null}
{
"message_type": "auth-request",
"card_id": "card_09876543421",
"amount": "10.00",
"currency": "USD",
"status": "pending",
"decline_reason": null,
"network": "mastercard",
"network_created_at": "2017-11-02T11:55:09Z",
"processor": "marqeta",
"id": "cnm_2345678901",
"created_at": "2017-11-02T11:55:14Z",
"updated_at": "2017-11-02T11:55:14Z",
"merchant": {
"name": "A VENDOR NAME",
"mid": "0123456789",
"mcc": "0000",
"address": {
"city": "EDGEWATER",
"state": "NJ",
"postal_code": "07020",
"country": "USA"
}
},
"atm": null,
"networkdata": {
"type": "authorization.incremental",
"state": "PENDING",
"token": "9699f5fc-3516-49c1-93a1-f6a9e6635bdf",
"user_token": "0146434d-3c22-4906-a538-b61d39cf6f71",
"acting_user_token": "0146434d-3c22-4906-a538-b61d39cf6f71",
"card_token": "028b20b2-215f-4ab4-a334-f08d99def0e4",
"created_time": "2022-09-29T21:35:03Z",
"user_transaction_time": "2022-09-29T21:35:03Z",
"settlement_date": "2022-09-29T00:00:00Z",
"request_amount": 10.00,
"amount": 10.00,
"issuer_interchange_amount": 0.00,
"currency_code": "USD",
"network": "MASTERCARD",
"acquirer_fee_amount": 0.00,
"card_acceptor": {
"mid": "123456890",
"mcc": "6411",
"name": "Marqeta Storefront",
"address": "330 Central Ave.",
"city": "St. Petersburg",
"state": "FL",
"postal_code": "33705",
"country_code": "USA"
},
"acquirer": null,
"card_security_code_verification": null,
"fraud": {
"network": {
"transaction_risk_score": 86,
"account_risk_score": 2
}
},
"pos": {
"pan_entry_mode": "MAG_STRIPE",
"pin_entry_mode": "TRUE",
"terminal_id": "TR100000",
"terminal_attendance": "ATTENDED",
"card_holder_presence": false,
"card_presence": false,
"partial_approval_capable": false,
"purchase_amount_only": false,
"is_recurring": false
}
}
}
```
The above example includes a sample of what might be received in the `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](https://www.marqeta.com/docs/core-api/gateway-jit-funding-messages).
## Card Event Webhooks
When Treasury Prime receives a new notification from the card network, a Card Event object is created. This results in the `card_event.create` [webhook](/reference/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.
##### Example card\_event.create Webhook
```bash bash theme={null}
{
"event": "card_event.create",
"op": "create",
"url": "https://api.sandbox.treasuryprime.com/card_event/cnm_112233sfbyf0qh",
"id": "cnm_11hejtsfbyf0qh"
}
```
## Card Event Status
Card events contain a `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. |
## Card Events by Type
These are the types of card events that you will encounter. See below for further descriptions and examples of each type of event.
* [`auth-request`](#authrequest)
* [`auth-capture`](#authcapture)
* [`auth-reversal`](#authreversal)
* [`incremental-auth-request`](#incrementalauthrequest)
* [`refund-auth-request`](#refundauthrequest)
* [`refund`](#refund)
* [`refund-auth-reversal`](#refundauthreversal)
* [`auth-standin`](#authstandin)
* [`force-capture`](#forcecapture)
* [`auth-clear-request`](#authclearrequest)
* [`auth-clear-adjustment`](#authclearadjustment)
* [`auth-clear-reversal`](#authclearreversal)
* [`balance-inquiry-request`](#balanceinquiryrequest)
* [`chargeback-request`](#chargebackrequest)
* [`chargeback-reversal`](#chargebackreversal)
* [`original-credit-auth-request`](#originalcreditauthrequest)
* [`original-credit-auth-clear-request`](#originalcreditauthclearrequest)
* [`account-verification-request`](#accountverificationrequest)
### auth-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](/reference/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.
#### Partial Authorizations
Partial authorizations can occur when a merchant sends an authorization request but the cardholder’s current balance is insufficient to cover the entire amount. In these instances, if the merchant supports partial authorizations, Treasury Prime will respond to the authorization request with the amount that is currently available in the user's account.
##### Example
A cardholder wishes to purchase \$25 worth of groceries, but only has \$10 available in their account. The merchant submits an `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
An `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 |
#### Partial Captures
Partial captures can occur when a merchant sends an authorization request for a higher amount than the final purchase.
##### Example
A cardholder swipes their card at an Automated Fuel Dispenser (AFD) to purchase some gas. The AFD sends an initial `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 |
#### Gas Stations and High Value Captures
Self-service gas pumps present a somewhat unique scenario where a low-value `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](/reference/card-auth-loop-endpoint) to review `auth-requests` from gas stations (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 %}
##### Example
A cardholder swipes their card at a gas station and an `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
An `auth-reversal` is used to cancel or reverse an authorization before the funds have been captured.
##### Example
A customer swipes their card to initiate a purchase, this results in an `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.
##### Scenario 1
| 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.
##### Scenario 2
`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 |
### incremental-auth-request
On occasion, a merchant may need to increase the amount of an earlier `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.
##### Example — Tipping in a Restaurant
An `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
A `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](/reference/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 |
### refund
When a merchant issues a refund to a card, a credit is issued to the users account in the amount of the refund, and will become immediately available.
| Object | Type | Amount |
| ----------- | ------- | ------ |
| Card Event | refund | 25 |
| Transaction | deposit | 25 |
### refund-auth-reversal
Reversal of a prior `refund-auth-request`
| Object | Type | Amount |
| ---------- | -------------------- | ------ |
| Card Event | refund-auth-request | 25 |
| Card Event | refund-auth-reversal | 25 |
### auth-standin
In circumstances where the issuer processor for the card is unable to respond to an authorization request (such as during an outage), the card network operator may need to step in and make a decision so the transaction can move forward without negatively impacting the cardholder. In these instances, known as “stand-in processing” or "STIP", an `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](/reference/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
A `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.
##### Scenario 1
The initial authorization has been reversed due to a network or issuer request (or for some other reason) requiring the merchant to use a `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 |
##### Scenario 2
The merchant does not send an initial `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 |
**Tips for Handling Force Captures**
A force capture occurs when a clearing message settles funds without a prior authorization, or when the prior authorization has already been reversed. This bypasses your Card Auth Loop Endpoint entirely—you do not get an opportunity to approve or decline the transaction.
One way to manage these risks is to monitor force capture frequency by merchant and MCC, maintain small buffer reserves to absorb unexpected captures, and implement alerting when force captures exceed thresholds. Force captures that exceed the cardholder's balance or appear fraudulent may also be candidates for chargeback.
### auth-clear-request
An `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-adjustment
This reduces the amount of a previous `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`.
##### Example
A cardholder attempts to make a purchase in the amount of \$50. The merchant sends an `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-reversal
This reverses a previous `auth-clear-request`
| Object | Type | Amount |
| ----------- | ------------------- | ------ |
| Card Event | auth-clear-request | 25 |
| Transaction | withdrawal | -25 |
| Card Event | auth-clear-reversal | 25 |
| Transaction | deposit | 25 |
### balance-inquiry-request
This is a request for the available balance of an account. This request is often associated with a cardholder request from an ATM.
| Object | Type | Amount |
| ---------- | ----------------------- | ------ |
| Card Event | balance-inquiry-request | 0 |
### chargeback-request
This is a request to issue a chargeback to the cardholders account. These most often occur as the result of a cardholders claim that a transaction was fraudulent.
| 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-reversal
This reverses a previous `chargeback-request`.
| Object | Type | Amount |
| ---------- | ------------------- | ------ |
| Card Event | chargeback-request | 25 |
| Card Event | chargeback-reversal | -25 |
### account-verification-request
Also known as a zero-dollar authorization, an `account-verification-request` authorizes an account without placing a hold on funds.
| Object | Type | Amount |
| ---------- | ---------------------------- | ------ |
| Card Event | account-verification-request | 0 |
### original-credit-auth-request
An `original-credit-auth-request` is sent when an Original Credit Transaction (OCT) is initiated to credit funds to a card. Unlike a refund, an OCT is not tied to a previous purchase — it represents a new inbound credit, such as a disbursement from a third-party service.
If using the [Card Auth Loop Endpoint](/reference/card-auth-loop-endpoint) to manage authorizations, you will receive a callback with `message_type` set to `original-credit-auth-request`, allowing you to distinguish incoming OCT credits from regular spending authorizations.
| Object | Type | Amount |
| ----------- | ---------------------------- | ------ |
| Card Event | original-credit-auth-request | 25 |
| Transaction | deposit | 25 |
### original-credit-auth-clear-request
An `original-credit-auth-clear-request` combines authorization and capture for an Original Credit Transaction (OCT) in a single message. Funds are credited immediately.
| Object | Type | Amount |
| ----------- | ---------------------------------- | ------ |
| Card Event | original-credit-auth-clear-request | 25 |
| Transaction | deposit | 25 |