type field further categorizes an event notification by specifying the attempted transaction type, and the transaction response code describes the outcome of that attempt. For example:
-
A combination of the
authorizationtransaction type and1001response code indicates a card authorization attempt that failed because the card was expired. -
A combination of the
authorizationorpindebittransaction type with a0000,0002, or1830response code indicates a successful transaction. All other response codes indicate failed transactions.
3D Secure transition events
3D Secure (3DS) transition events include activities for when a merchant requests 3D Secure authentication for a transaction (i.e., thethreedstransition.initialization event), as well as when the Marqeta platform sends the merchant the outcome of the authentication request (i.e., the threedstransition.completion event).
The Marqeta platform supports 3D Secure version 2.x.
The following example shows a 3D Secure 2.x initialization notification message:
JSON
JSON
Account holder transition events
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.
JSON
usertransitions object, see Users. For more information about the businesstransitions object, see Businesses.
ACH origination transition events
ACH Origination transition events include activities such as a 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 EventTypebanktransfertransition.
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.
JSON
banktransfers object, see Funding via ACH.
Bill payment transition events
Bill payment transition events include activities such as a bill payment being transitioned to a pending, completed, failed, returned, or canceled state. Bill payment transition notifications are sent when status transition events occur and contain detailed information about the events. Transition events will be sent with thebillpayment event type.
Bill payment transition notifications are structured as an array within a
billpayment element. Multiple notifications can be included in a single notification message. The structure of each individual notification is identical to that of a billpayment object returned by the /billpay/payments endpoint.
The following example shows a notification message containing a notification that a bill payment has been submitted and is in the COMPLETED state.
JSON
Card transition events
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’sstate 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.
JSON
cardtransitions object, see Cards.
Card action events
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 atype 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.
JSON
Chargeback transition events
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’sstate 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:
JSON
prearbitration.responded event, specific to Fraud and Authorization reason codes only:
JSON
Commando Mode transition events
Commando Mode transition events include enabling and disabling a Commando Mode control set for the associated program gateway funding source. These activities transition thecurrent_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.
JSON
commandomodes object, see Commando Mode.
Credit account delinquency state transition events
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’sis_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.
JSON
creditdelinquencytransitions object, see Retrieve delinquency state transition.
Credit account payment transition events
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’sstatus 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.
JSON
creditpaymenttransitions object, see Transition account payment status.
Credit account statement event
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 thetype 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.
JSON
creditaccountstatements object, see Retrieve account statement summary.
Credit account transition events
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’sstatus 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.
JSON
creditaccounttransitions object, see Retrieve account transition.
Credit journal entry events
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 atype 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.
JSON
creditjournalentries object, see Retrieve account journal entry.
Credit ledger entry events
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 atype 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.
JSON
creditledgerentries object, see Retrieve account ledger entry.
Credit product transition events
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 astatus 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.
JSON
creditproducttransitions object, see Retrieve credit product.
Credit reward entry events
Credit reward entry events include information about credit reward activity, such as creating a credit reward entry or posting a credit reward entry to a credit account. Credit reward entry notifications are sent when credit reward entry events occur. These notifications contain detailed information about credit reward entry events, such as the transaction amount, the value of the credit reward entry, and any related tokens. For more on webhooks, see Webhooks. The following example shows a notification for acreditrewardentry event.
JSON
Credit reward accounts events
Credit reward account events include information related to a reward account: for example, whether the credit reward account is active or not, and any credit rewards rules associated with it. For more on webhooks, see Webhooks. The following example shows a notification for acreditrewardaccounts event.
JSON
Credit reward redemptions events
Credit reward redemption events include information about the credit reward redemption type, destination, amount, and currency. Credit reward redemption events can also include information about the conversion rate between credit rewards points and dollar amounts to be credited to the corresponding credit account, if the redemption type is set toSTATEMENT_CREDIT.
For more on webhooks, see Webhooks.
The following example shows a notification for a creditredemptions event.
JSON
Credit substatus events
Credit substatus events occur when a substatus is applied or removed from a resource. When configuring a webhook to subscribe to credit events, set thetype value to credit.*. This enables Marqeta to send notifications for all credit events, including credit substatus events. For more information, see Webhooks.
The following example shows a
credit.substatus event in which a substatus is added to a resource.
JSON
credit.substatus event for updating a substatus.
JSON
Digital wallet token check eligibility event
The check eligibility event is only applicable to Visa token provisioning.
token.checkeligibility event to receive notifications when a provision request is declined because the card failed the eligibility check, giving you visibility into failed provisioning attempts and potential fraudulent activity such as bank identification number (BIN) enumeration attacks.
To subscribe to this event, include token.checkeligibility in the events array when you create or update a webhook.
The following example shows a token.checkeligibility notification.
JSON
Digital wallet token transition events
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’sstate 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).
Note
The token-related event type
token.activation-request is categorized as a transaction event and is documented in the Transaction events section.update is triggered when the reason field is populated with one of the values from the following table:
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.
JSON
digitalwallettokentransitions object, see Digital Wallets Management.
Direct deposit transition events
Direct deposit transition events include activities such as a direct deposit being applied, reversed, rejected, or set to pending. Transitioning the ACH transaction’sstate 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.
JSON
directdeposittransition.reversed event, when the available balance is insufficient to cover the dollar value of the debit entry.
JSON
directdeposittransition.rejected event, when the account could not be located.
JSON
directdeposittransition.rejected event, when the originator’s identity is unknown or the originator is not authorized to debit.
JSON
directdeposittransition.pending event.
JSON
/directdeposits/transitions endpoint, see ACH Receiving.
Direct deposit account transition events
Direct deposit account transition events include activities such as a direct deposit account being activated, suspended, or terminated. Updating the account’sstate 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.
JSON
/depositaccounts/transitions endpoint, see Deposit Accounts.
KYB results event
Thekybresults 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.
Note
The
VENDOR_PENDING status only applies to the BUSINESS component, not to the PROPRIETOR or BENEFICIAL_OWNER components. Therefore, the kybresults event only returns information about the BUSINESS component.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.
JSON
outcome_reasons in the kybresults array, see Business KYC outcome reasons.
Level 2 and Level 3 card data events
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 thetype value to authorization.clearing.l2l3.
The following example shows an authorization.clearing.l2l3 event.
JSON
JSON
Smart rejects
When a user submits a dispute that would eventually be rejected by the network, smart reject rules allow those disputes to be rejected earlier in the dispute lifecycle, minimizing the operational cost. Smart rejects are implemented through webhooks. Thecases 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 are disputes with smart reject rules:
- Fraud dispute on a 3DS transaction
- Incorrect Transaction Amount without supporting document
Smart reject for 3DS case events
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 thetype value in the subscription request to caseevent.*.
The following example shows the cases.smart.reject event.
JSON
Smart reject for Incorrect Transaction Amount without supporting document
If you initiate a dispute with the network using the/cases endpoint without a copy of the transaction receipt or other record with the correct transaction amount, the dispute will be smart rejected and the moved to Open with Action Required.
The following example shows the cases.smart.reject event.
JSON
Transaction events
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 atype 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.
JSON
Possible values for cardholder_presence field
Possible values for card_presence field
For more information about the
transactions object, see Transactions.