Event Types

3D Secure (3DS) transition events include activities for when a merchant requests 3D Secure authentication for a transaction (i.e., the threedstransitions.initialization event), as well as when the Marqeta platform sends the merchant the outcome of the authentication request (i.e., the threedstransitions.completion event).

The Marqeta platform supports 3D Secure versions 1.x and 2.x. The webhook notifications will differ slightly, depending on the version of 3D Secure you are using.

The following example shows a 3D Secure 1.x initialization notification message:

The following example shows a 3D Secure 1.x completion notification message:

The following example shows a 3D Secure 2.x initialization notification message:

The following example shows a 3D Secure 2.x completion notification message:

For more information about 3D Secure, see 3D Secure Overview.

Account holder transition events include activities such as a user or business being created, suspended, or closed. These activities transition a user’s or business' status.

Account holder transition notifications contain detailed information about the events, along with any metadata associated with the user or business account holder. They are sent as account holder transition events occur.

Each notification contains a status field that categorizes the account holder transition event. The following table describes each account holder status. Values in the Status column are the literal values of the notification’s status field. When configuring a webhook to capture these events, you must prefix this with usertransition or businesstransition (for example, usertransition.active).

Account holder transition notifications are structured as an array within a usertransitions or businesstransitions element. Multiple notifications can be included in a single notification message. The structure of each individual notification is identical to that of a usertransition or businesstransition object returned by the /usertransitions and /businesstransitions endpoints, respectively.

The following example shows a notification message containing a business transition notification, indicating the business was closed.

For more information about the usertransitions object, see Users. For more information about the businesstransitions object, see Businesses.

ACH Origination transition events include activities such as bank transfer being transitioned to a pending, processing, submitted, completed, returned, or cancelled state. ACH transfer transition notifications are sent when status transition events occur and contain detailed information about the events.

Transition events will be sent with the EventType banktransfertransition.

Bank transfer transition notifications are structured as an array within a banktransfertransitions element. Multiple notifications can be included in a single notification message. The structure of each individual notification is identical to that of a banktransfertransition object returned by the /banktransfertransitions endpoint.

The following example shows a notification message containing a notification that a bank transfer transition has been submitted.

For more information about the banktransfers object, see Funding via ACH.

Card transition events include activities such as a card being activated/deactivated, ordered, or shipped. From a technical point of view, they are activities that cause the transition of a card’s state or fulfillment_status field.

Card transition notifications are sent as card transition events occur and contain detailed information about the events, along with any metadata associated with the card.

Each notification contains a type field that categorizes the card transition event. The following table describes each card transition event type. The values in the Type column are the literal values of the notification’s type field. When configuring a webhook to capture card events, you must prefix this type with cardtransition (for example, cardtransition.fulfillment.issued).

Card transition notifications are structured as an array within a cards element. Multiple notifications can be included in a single notification message. The structure of each individual notification is identical to that of a cardtransition object returned by the /cardtransitions endpoint.

The following example shows a notification message containing two card transition notifications: one for the issuance of a card, and one for the activation of that card.

For more information about the cardtransitions object, see Cards.

Card action events include PIN set, PIN change, and PIN reveal actions. Card action notifications are sent as card action events occur and contain detailed information about the events.

Each notification contains a type field that categorizes the card action event. The following table describes each card action event type. The values in the Type column are the literal values of the notification’s type field. When configuring a webhook to capture these events, you must prefix this type with cardaction (for example, cardaction.pin.set).

The following example shows a notification message containing a notification that a PIN was set for a card.

Chargeback transition events mark the progress of disputes through the arbitration process. From a technical point of view, chargeback transition events cause the transition of a chargeback object’s state field.

The chargeback object represents a completed transaction that has been disputed by the issuer. In order for the dispute to be resolved, the chargeback must pass through an arbitration process consisting of multiple phases. Each phase of the arbitration process is represented by a chargebacktransition object of a particular type. For example, the creation of a new chargeback incidentally creates a chargebacktransition of type initiated. After creating a chargeback, you can explicitly move it from one arbitration phase to another by creating a chargebacktransition of the appropriate type. Chargebacks do not follow a prescribed path through the arbitration process.

Chargeback transition notifications are sent as chargeback transition events occur and contain detailed information about the events.

Each notification contains a type field that categorizes the chargeback transition event. The following table describes each chargeback transition event type. The values in the Type column are the literal values of the notification’s type field. When configuring a webhook to capture these events, you must prefix this type with chargebacktransition (for example, chargebacktransition.representment).

Chargeback transition notifications are structured as an array within a chargebacktransitions element. Multiple notifications can be included in a single notification message.

The following example shows a notification message containing two chargeback transition notifications:

The following example shows a notification message for a prearbitration.responded event, specific to Fraud and Authorization reason codes only:

Commando Mode transition events include enabling and disabling a Commando Mode control set for the associated program gateway funding source. These activities transition the current_state.commando_enabled field of a specific Commando Mode control set.

Commando Mode transition notifications are sent as transition events occur and contain detailed information about the events. When configuring a webhook to capture these events, you must prefix the event type (such as enabled or disabled) with commandomodetransition. For example, to capture when a Commando Mode control set is enabled, you must configure a webhook for the commandomodetransition.enabled event.

The following table describes each Commando Mode transition event type.

The following example shows a notification message containing a Commando Mode transition notification, indicating the Commando Mode control set was disabled.

For more information about the commandomodes object, see Commando Mode.

Credit account delinquency state transition events occur when a credit account becomes delinquent and falls behind on its payments or becomes current and is brought up to date on its payments. These events cause the delinquency state’s is_delinquent field to toggle between true and false.

Delinquency state transition notifications are sent as delinquency state transition events occur and contain detailed information about the events.

Each notification contains a status field that indicates the account’s new delinquency status. The following table describes each delinquency status. Values in the Status column are the literal values of the notification’s status field. Values in the Type field are the literal webhook event type.

When configuring a webhook to subscribe to credit events, set the type value to credit.*. This enables Marqeta to send notifications for all credit events, including credit account delinquency state transition events. The ability to receive individual credit events will be available in a future release. For more on webhooks, see Webhooks

The following example shows a credit.delinquencytransition.current event.

For more information about the creditdelinquencytransitions object, see Retrieve delinquency state transition.

The following applies to ACH payments on credit accounts only.

Credit account payment transition events include activities such as a payment being initiated, submitted, or returned on a credit account. From a technical point of view, they are activities that cause the transition of a payment’s status field.

Payment transition notifications are sent as payment transition events occur and contain detailed information about the events.

Each notification contains a status field that categorizes the payment transition event. The following table describes each payment status. Values in the Status column are the literal values of the notification’s status field.

When configuring a webhook to subscribe to credit events, set the type value to credit.*. This enables Marqeta to send notifications for all credit events, including credit account payment transition events. The ability to receive individual credit events will be available in a future release. For more on webhooks, see Webhooks

The following example shows a credit.paymenttransition.completed event.

For more information about the creditpaymenttransitions object, see Transition account payment status.

The credit account statement event occurs when a statement is generated on the billing cycle day and contains detailed information about the statement, including the opening date, closing date, closing balance, and more.

When configuring a webhook to subscribe to credit events, set the type value to credit.*. This enables Marqeta to send notifications for all credit events, including the credit account statement event. The ability to receive individual credit events will be available in a future release. For more on webhooks, see Webhooks

The following example shows a credit.accountstatement.created event.

For more information about the creditaccountstatements object, see Retrieve account statement summary.

Credit account transition events include activities such as a credit account being activated, unactivated, suspended, or terminated. From a technical point of view, they are activities that cause the transition of a credit account’s status field.

Credit account transition notifications are sent as the credit account transition events occur and contain detailed information about the events.

Each notification contains a status field that indicates the account’s new status. The following table describes each credit account status. Values in the Status column are the literal values of the notification’s status field. Values in the Type field are the literal webhook event type.

When configuring a webhook to subscribe to credit events, set the type value to credit.*. This enables Marqeta to send notifications for all credit events, including credit account transition events. The ability to receive individual credit events will be available in a future release. For more on webhooks, see Webhooks

The following example shows a credit.accounttransition.status.activated event.

For more information about the creditaccounttransitions object, see Retrieve account transition.

Credit application transition events include activities such as an application being created, submitted, rejected, accepted, and more. From a technical point of view, they are activities that cause the transition of an application’s state field.

Application transition notifications are sent as application transition events occur and contain detailed information about the events.

Each notification contains a status field that categorizes the application transition event. The following table describes each application status. Values in the Status column are the literal values of the notification’s status field.

When configuring a webhook to subscribe to credit events, set the type value to credit.*. This enables Marqeta to send notifications for all credit events, including application events. The ability to receive individual credit events will be available in a future release. For more on webhooks, see Webhooks

The following example shows a credit.applicationtransitions.status.decisioning event.

For more information about the applicationtransitions object, see Transition application state.

The following applies to credit journal entry events only. For debit transactions, see Transaction events.

Journal entry events include activities on a credit account such as purchase authorizations, purchase authorization clearings, refunds, credit balance refunds, adjustments, fees, interest, rewards, and payments. Although you might think of a purchase authorization and purchase authorization clearing as two parts of the same conceptual journal entry, the Marqeta platform treats each journal entry-related message exchange as a separate journal entry event with a unique identifying token.

Journal entry notifications are sent in real time as journal entry events occur and contain detailed information about the events.

All journal entry notifications contain a type field that categorizes the journal entry event. The following table lists all possible values for the type field. The values in the Type column are the literal values of the notification’s type field.

When configuring a webhook to subscribe to credit events, set the type value to credit.*. This enables Marqeta to send notifications for all credit events, including journal entry events. The ability to receive individual credit events will be available in a future release. For more on webhooks, see Webhooks

Journal entry notifications are structured as an array within a creditjournalentries element.

The following is a sample purchase journal entry notification. The detail_object contains the purchase details, in this case. However, fields in the detail_object vary based on the group value. For example, purchases return purchase details; adjustments return adjustment details; interest returns interest details.

The following example shows a credit.journalentry.authorization event.

For more information about the creditjournalentries object, see Retrieve account journal entry.

Ledger entry events include activities on a credit account such as purchase authorizations, purchase authorization clearings, refunds, credit balance refunds, adjustments, fees, interest, rewards, and payments. Although you might think of a purchase authorization and purchase authorization clearing as two parts of the same conceptual ledger entry, the Marqeta platform treats each ledger entry-related message exchange as a separate ledger entry event with a unique identifying token.

Ledger entry notifications are sent in real time as ledger entry events occur and contain detailed information about the events.

All ledger entry notifications contain a type field that categorizes the ledger entry event. The following table lists all possible values for the type field. The values in the Type column are the literal values of the notification’s type field.

When configuring a webhook to subscribe to credit events, set the type value to credit.*. This enables Marqeta to send notifications for all credit events, including ledger entry events. For more on webhooks, see Webhooks

Ledger entry notifications are structured as an array within a creditledgerentries element.

The following is a sample purchase ledger entry notification. The detail_object contains the purchase details, in this case. However, fields in the detail_object vary based on the group value. For example, purchases return purchase details; adjustments return adjustment details; interest returns interest details.

The following example shows a credit.ledgerentry.authorization event.

For more on the creditledgerentries object, see Retrieve account ledger entry.

Credit product transition events include activities such as a credit product being activated, pending approval, sent for revision, or rejected. These activities transition a credit product’s status.

Credit product transition notifications contain detailed information about the events. They are sent as credit product transition events occur.

Each notification contains a status field that categorizes the credit product transition event. The following table describes each credit product status. Values in the Status column are the literal values of the notification’s status field. Values in the Type field are the literal webhook event type.

When configuring a webhook to subscribe to credit events, set the type value to credit.*. This enables Marqeta to send notifications for all credit events, including credit product transition events. For more on webhooks, see Webhooks

The following example shows a credit.producttransition.state.activated event.

For more on the creditproducttransitions object, see Retrieve credit product.

Credit reward entry events include activities such as a reward entry being created or posted to a credit account. From a technical point of view, they are activities that cause the transition of a reward entry’s status field.

Reward entry notifications are sent as reward entry events occur and contain detailed information about the events.

Each notification contains a status field that categorizes the reward entry event. The following table describes each reward entry status. Values in the Status column are the literal values of the notification’s status field.

When configuring a webhook to subscribe to credit events, set the type value to credit.*. This enables Marqeta to send notifications for all credit events, including reward entry events. The ability to receive individual credit events will be available in a future release. For more on webhooks, see Webhooks

The following example shows a creditrewardentries.pending event.

For more information about the creditrewardentries object, see Retrieve reward entry.

Credit reward redemption transition events include activities such as an reward redemption being initated, completed, or returned. From a technical point of view, they are activities that cause the transition of a reward redemption’s status field.

Reward redemption transition notifications are sent as reward redemption transition events occur and contain detailed information about the events.

Each notification contains a status field that categorizes the reward redemption transition event. The following table describes each redemption status. Values in the Status column are the literal values of the notification’s status field.

When configuring a webhook to subscribe to credit events, set the type value to credit.*. This enables Marqeta to send notifications for all credit events, including reward redemption events. The ability to receive individual credit events will be available in a future release. For more on webhooks, see Webhooks

The following example shows a creditredemptiontransitions.initiated event.

For more information about the creditredemptiontransitions object, see Create reward redemption.

Digital wallet token transition events include activities such as a digital wallet token being requested, activated, or terminated. From a technical point of view, they are activities that cause the transition of a token’s state or fulfillment_status field.

Digital wallet token transition notifications are sent as digital wallet token transition events occur and contain detailed information about the events.

Each notification contains a type field that categorizes the digital wallet token transition event. The following table describes each digital wallet token transition event type. The values in the Type column are the literal values of the notification’s type field. When configuring a webhook to capture digital wallet token events, you must prefix this type with digitalwallettokentransition (for example, digitalwallettokentransition.fulfillment.requested).

Digital wallet token transition notifications are structured as an array within a digitalwallettokentransitions element. Multiple notifications can be included in a single notification message. The structure of each individual notification is identical to that of a digitalwallettokentransition object returned by the /digitalwallettokentransitions API endpoint.

The following example shows a notification message containing two digital wallet token transition notifications: one requesting a token, and one for the activation of that token.

For more information about the digitalwallettokentransitions object, see Digital Wallets Management.

Direct deposit transition events include activities such as a direct deposit being applied, reversed or rejected. Transitioning the ACH transaction’s state field triggers these event notifications.

Each notification contains a state field that indicates the ACH transaction’s new state. The following table describes the possible values of the state field within a directdeposittransition event. Values under the State column are the literal values of the notification’s state field. When configuring a webhook to capture these events, you must prefix this with directdeposittransition (for example, directdeposittransition.applied).

The following example shows a directdeposittransition.applied event.

For more information about the /directdeposits/transitions endpoint, see Direct Deposit.

Direct deposit account transition events include activities such as a direct deposit account being activated, suspended, or terminated. Updating the account’s state field triggers these event notifications.

Direct deposit account transition notifications are sent as the corresponding transition events occur. Each notification contains a state field that indicates the account’s new state. The following table describes the possible values of the state field within a directdepositaccounttransition event. Values in the State column are the literal values of the notification’s state field. When configuring a webhook to capture these events, you must prefix this with directdepositaccounttransition (for example, directdepositaccounttransition.active).

The following example shows a directdepositaccounttransition.suspended event.

For more information about the /depositaccounts/transitions endpoint, see Deposit Accounts.

The kybresults event returns the results of a KYC verification request for a business when the BUSINESS component could not be verified in the allotted time. In such cases, the KYC request returns a status of VENDOR_PENDING, and the relevant BUSINESS component also returns an outcome of VENDOR_PENDING.

Marqeta sends kybresults events as soon as the KYC vendor returns the final verification for the business KYC verification request.

The following example shows a kybresults event that returned a successful KYC result for a business. The token field includes the original KYC request token from the POST /kyc action. See Perform KYC for information about the POST /kyc action.

For more information about the business.results object, see the business result array.

Level 2 (L2) and Level 3 (L3) card data go beyond standard Level 1 (L1) data such as card number and transaction amount. L2 and L3 data provide more specific data to the merchants, issuers, acquirers, and processors that transact with business, corporate, and purchasing cardholders. These services enable the processing and delivery of additional transaction data to help merchants and issuers gather important non-financial data from commercial card transactions.

L2 data include L1 data plus details such as sales tax amount and purchase order number. L3 data include L1 and L2 data plus additional details such as product quantity, line item description, and unit of measure.

When configuring a webhook to subscribe to L2 and L3 card data events, set the type value to authorization.clearing.l2l3.

The following example shows an authorization.clearing.l2l3 event.

This is the model for L2/L3 card transaction data.

When a user attempts to submit a fraud dispute on a 3DS transaction, the case management system smart-rejects the dispute. 3DS rejections apply to fraud disputes (10.1, 10.2, 10.3, 10.4). When configuring a webhook to subscribe to smart reject events, set the type value in the subscription request to caseevent.*.

The cases object represents a smart rejection that has been submitted. Notifications that are sent contain detailed information about the case event. Each notification contains a type field that categorizes the case event. When configuring a webhook to capture case events, you must prefix this type with cases (for example, cases.smart.reject).

The following example shows a cases.smart.reject event.

The following applies to debit transaction events only. For credit journal entries, see Credit journal entry events.

Transaction events include activities such as authorizations, authorization clearings, and refunds. Although you might think of an authorization and authorization clearing as two parts of the same conceptual transaction, the Marqeta platform treats each transaction-related message exchange as a separate transaction event with a unique identifying token.

Transaction notifications are sent in real time as transaction events occur; they contain detailed information about the events.

All transaction notifications contain a type field that categorizes the transaction event. The following table lists all possible values for the type field. The table describes each type, indicates the objects potentially included in that transaction type, and lists the transaction types that could potentially complete it. The values in the Type column are the literal values of the notification’s type field. When configuring a webhook to capture these events, you must prefix this type with transaction (for example, transaction.authorization).

The response.code field describes the outcome of the attempted transaction. For more information on transaction outcomes, see the transaction response codes table.

See all transaction response fields in Transactions.

The following is a sample transaction notification. The type and amount fields are always returned. Other fields and object groups are conditionally returned. Refer to the preceding table for a list of objects possibly included for each transaction type.