Skip to main content
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

{
  "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",
    "digital_wallet_token": {
      "token": "4c72bc11-1574-48c3-8cba-586072a7432f",
      "card_token": "IC_4e3omf16hwgbfpt7pumg6tfky",
      "state": "ACTIVE",
      "device": {
        "type": "MOBILE_PHONE",
        "language_code": "eng",
        "device_id": "0423117BE44E80018327074341948822B514D73218EB41DE",
        "phone_number": "14088581301",
        "name": "iPhone",
        "location": "+35.96/-78.85",
        "ip_address": "101.203.084.990"
      },
      "address_verification": {
        "name": "",
        "street_address": "180 Grand Ave",
        "zip": "**MASKED**"
      }
    },
    "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.

​
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 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
{
  "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:
StatusDescription
pendingActionable 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.
errorAn internal or other error has been encountered.
approvedThe card event has been approved.
deniedThe card event has been denied.
timeoutA 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.
receivedThis 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, there are further details and examples below.

​
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 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).
ObjectTypeAmount
Card Eventauth-request25
Transactionhold-10
Card Eventauth-capture10
Transactionhold_release25
Transactionwithdrawal-10
Transactionhold-15
Transactionhold_release15

​
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.
ObjectTypeAmount
Card Eventauth-request20
Transactionhold-20
Card Eventauth-capture20
Transactionhold_release20
Transactionwithdrawal-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).
ObjectTypeAmount
Card Eventauth-request100
Transactionhold-100
Card Eventauth-capture50
Transactionhold_release100
Transactionwithdrawal-50
Transactionhold-50
Transactionhold_release50

​
Automated Fuel Dispensers and High Value Captures

Automated Fuel Dispensers (AFD’s) 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 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 %}
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.
ObjectTypeAmount
Card Eventauth-request1
Transactionhold-1
Card Eventauth-capture50
Transactionhold_release1
Transactionwithdrawal-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
ObjectTypeAmount
Card Eventauth-request25
Card Eventauth-reversal25
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.
ObjectTypeAmount
Card Eventauth-request25
Transactionhold-25
Transactionhold_release25
Card Eventauth-reversal25

​
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).
ObjectTypeAmount
Card Eventauth-request10
Transactionhold-10
Card Eventincremental-auth-request5
Transactionhold_release10
Transactionhold-15
Card Eventauth-capture15
Transactionhold_release15
Transactionwithdrawal-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, a webhook callback will be triggered in response to this event, allowing you to approve or deny the request.
ObjectTypeAmount
Card Eventrefund-auth-request25
Card Eventrefund25
Transactiondeposit25

​
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.
ObjectTypeAmount
Card Eventrefund25
Transactiondeposit25

​
refund-auth-reversal

Reversal of a prior refund-auth-request
ObjectTypeAmount
Card Eventrefund-auth-request25
Card Eventrefund-auth-reversal25

​
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, and you will not be able to decline the authorization.
ObjectTypeAmount
Card Eventauth-standin25
Transactionhold-25
Card Eventforce-capture25
Transactionhold_release25
Transactionwithdrawal-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.
DateObjectTypeAmount
2022-04-19Card Eventauth-request25
2022-04-19Transactionhold-25
2022-04-28Card Eventauth-reversal25
2022-04-28Transactionhold_release25
2022-05-10Card Eventforce-capture25
2022-05-10Transactionwithdrawal-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.
DateObjectTypeAmount
2022-04-19Card Eventforce-capture25
2022-05-10Transactionwithdrawal-25

​
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.
DateObjectTypeAmount
2022-04-19Card Eventauth-clear-request25
2022-04-19Transactionwithdrawal-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.
ObjectTypeAmount
Card Eventauth-clear-request50
Transactionwithdrawal-25
Card Eventauth-clear-adjustment5
Transactiondeposit5

​
auth-clear-reversal

This reverses a previous auth-clear-request
ObjectTypeAmount
Card Eventauth-clear-request25
Transactionwithdrawal-25
Card Eventauth-clear-reversal25
Transactiondeposit25

​
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.
ObjectTypeAmount
Card Eventbalance-inquiry-request0

​
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.
ObjectTypeAmount
Card Eventauth-request25
Transactionhold-25
Card Eventauth-capture25
Transactionhold_release25
Transactionwithdrawal-25
Card Eventchargeback-request25
Transactiondeposit25

​
chargeback-reversal

This reverses a previous chargeback-request.
ObjectTypeAmount
Card Eventchargeback-request25
Card Eventchargeback-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.
ObjectTypeAmount
Card Eventaccount-verification-request0
⌘I