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

{
  "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:

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-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 Card Events

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).

auth-capture Card Events

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.

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).

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.

auth-reversal Card Events

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.

auth-reversal Scenario 1

auth-reversal submitted before the auth-request has been approved and a hold has been created.

auth-reversal Scenario 2

auth-reversal submitted after the auth-request has been approved and a hold has been created.

incremental-auth-request Card Events

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).

refund-auth-request Card Events

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.

refund Card Events

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.

refund-auth-reversal Card Events

Reversal of a prior refund-auth-request

auth-standin Card Events

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.

{% alert severity="warning" %}
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.
{% /alert %}

force-capture Card Events

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.

force-capture 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.

force-capture 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.

auth-clear-request Card Events

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.

auth-clear-adjustment Card Events

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.

auth-clear-reversal Card Events

This reverses a previous auth-clear-request

balance-inquiry-request Card Events

This is a request for the available balance of an account. This request is often associated with a cardholder request from an ATM.

chargeback-request Card Events

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.

chargeback-reversal Card Events

This reverses a previous chargeback-request.

account-verification-request Card Events

Also known as a zero-dollar authorization, an account-verification-request authorizes an account without placing a hold on funds.