Business Flows

JIT transaction lifecycle

Transactions can be authorized, cleared, and settled either as dual-message transactions or as single-message transactions. The processing method may vary depending upon the payment method issuer, the card type, or the region where the transaction takes place:

  • In a single-message transaction, the merchant submits a single electronic message containing all data required for the authorization, clearing, and settlement of the transaction.

  • In a dual-message transaction, at the time of purchase, the merchant submits an electronic message containing the information required for an authorization decision. The merchant later submits a second message containing the data required for clearing and settlement.

The Marqeta platform creates transaction objects from the electronic messages received from the card network. Except from the state attribute, once created, transaction objects are immutable.

How transactions transition through different states during their lifecycle depends on whether they are temporary or final transactions. Temporary and final transactions are closely related to single-message and dual-message transactions.

A dual-message transaction requires two or more transaction messages to complete, for example:

  • At the time of purchase, the merchant submits an electronic message containing the information required for an authorization decision.
  • The merchant later submits another electronic message containing any other data required for clearing and settlement.

In this scenario, the first message is a temporary transaction, which means it can be reversed. The last message is a final transaction. Temporary transaction messages, such as authorizations, are handled synchronously, which means a transaction message flows in real time from the merchant to the issuer processor and then back to the merchant. Final transaction messages are handled asynchronously, because capture requests can be submitted at a later time.

Marqeta connector handles both single-message and dual-message transactions. The tables below contain details on the types of actionable and informative events processed by the connector.

JIT actionable events

Marqeta eventEvent stateSingle messageDual message
balanceinquiryPENDING
pindebit.balanceinquiryPENDING
authorizationPENDING
authorization.incrementalPENDING
refund.authorizationPENDING
original.credit.authorizationPENDING
authorization.quasi.cashPENDING
authorization.atm.withdrawalPENDING
authorization.cashbackPENDING
account.funding.authorizationPENDING
pindebit.authorizationPENDING
pindebitCOMPLETION
pindebit.atm.withdrawalCOMPLETION
pindebit.cashbackCOMPLETION
original.credit.auth_plus_captureCOMPLETION

JIT informative events

Marqeta eventEvent stateSingle messageDual message
authorization.clearing.representmentCOMPLETION
authorization.clearingCOMPLETION
authorization.clearing.atm.withdrawalCOMPLETION
authorization.clearing.quasi.cashCOMPLETION
authorization.clearing.cashbackCOMPLETION
authorization.standinPENDING
pindebit.authorization.clearingCOMPLETION
authorization.clearing.chargebackCOMPLETION
authorization.clearing.chargeback.completedCOMPLETION
pindebit.chargebackCOMPLETION
pindebit.chargeback.completedCOMPLETION
pindebit.refundCOMPLETION
pindebit.reversalCOMPLETION
account.funding.authorization.clearingCOMPLETION
refund.authorization.clearingCOMPLETION
original.credit.authorization.clearingCOMPLETION
refundCOMPLETION
pindebit.refund.reversalCOMPLETION
original.credit.auth_plus_capture.reversalCOMPLETION
authorizationDECLINED
CLEARED
authorization.atm.withdrawalDECLINED
CLEARED
authorization.quasi.cashDECLINED
CLEARED
refund.authorizationDECLINED
CLEARED
original.credit.authorizationDECLINED
CLEARED
authorization.cashbackDECLINED
CLEARED
account.funding.authorizationDECLINED
CLEARED
pindebit.authorizationDECLINED
CLEARED
authorization.incrementalDECLINED
authorization.reversalCLEARED
authorization.advicePENDING
authorization.reversal.issuerexpirationCLEARED
pindebit.authorization.reversal.issuerexpirationCLEARED
original.credit.authorization.reversalCLEARED
refund.authorization.reversalCLEARED
account.funding.authorization.reversalCLEARED
authorization.clearing.chargeback.reversalCLEARED
pindebit.chargeback.reversalCLEARED
authorization commando modePENDING
authorization.atm.withdrawal commando modePENDING
authorization.cashback commando modePENDING
authorization.quasi.cash commando modePENDING
pindebit.authorization commando modePENDING
account.funding.authorization commando modePENDING
account.incremental commando modePENDING
pindebit commando modePENDING
pindebit.atm.withdrawal commando modePENDING
pindebit.cashback commando modePENDING
original.credit.auth_plus_capture commando modePENDING

Business flows

The main business flows supported by the Mambu - Marqeta connector are initiated by either an actionable or an informative event.

Actionable events

The JIT Actionable Receiver process handles authorization holds, the creation of financial transactions, balance inquiries, and authorization incremental requests. The JIT Actionable Receiver can be called synchronously using the MPO Sync API. For these types of events, Marqeta requires a response from the connector. More details about the expected response in case of success or error and response time limitations can be provided by your Integration Consultant.

The categories of events that are processed by the JIT Actionable Receiver are:

  • Debit Authorization events
  • Credit Authorization events
  • Authorization Incremental events
  • Debit Financial Transaction events
  • Credit Financial Transaction events
  • Balance Inquiry events

Please note The Marqeta Connector supports custom fields logic at the transaction level. At the same time, transactions can be posted on different transaction channels, each of them with the possibility of having a dedicated general ledger account linked.

Informative events

The JIT Informative Notifications Receiver process handles clearing and chargeback transactions, reversals, declined authorizations, authorization decrease, authorization stand-in requests and commando mode events processing. The JIT Informative Receiver can be called synchronously via the MPO sync API.

This process has two main responsibilities, event validation and processing valid events.

Incoming events are validated for the presence of mandatory parameters and a response sent to Marqeta indicating whether the batch is valid or not. Only events that are finalised by a financial transaction are subjected to the batch validation process.

Each event to be filtered is checked for the presence of the following parameters: state, token, card_token, currency_code. The jit_funding object is checked only for clearing transactions that have funding source type programgateway.

The list of parameters to be validated is configurable.

Chargeback events are also validated for the presence of thechargeback object and chargeback.token only if the gpa_order_unload.jit_funding object is present in the payload. Two cases can occur for these events:

  • If the gpa_order_unload.jit_funding object is present, batch validation continues with checks for the presence of state, token, card_token and currency_code parameters.
  • If the gpa_order_unload.jit_funding object is not present, batch validations are skipped and the event is ignored.

Each incoming event is also checked for the presence of the parameter type, which is a decision related to the transaction type that needs to be posted in Mambu. The type parameter takes a dedicated value that is later used in the routing logic.

If the batch is valid, the transactions are processed one-by-one by sending them to the corresponding sub-process responsible for handling the specific event type.

The main categories of events that are processed by the JIT Informative Receiver are:

  • Debit authorization clearing and financial transaction
  • Credit authorization clearing and financial transaction
  • Declined or expired authorization holds which trigger a reverse authorization hold action in Mambu
  • Authorization reversal and decrease which trigger a decrease authorization hold action in Mambu
  • Authorization stand-in which creates an authorization hold on a card account without checking available balance
  • Authorization holds and incrementals under commando mode created without checking available balance
  • Reverse Card Transactions

Under certain conditions, if processing of the transaction fails due to technical errors which might occur in the JIT Informative Receiver, the processing of failed transactions is resumed.

Commando mode

Commando Mode is a fallback measure that ensures Gateway JIT-funded cards continue to function in the event that the JIT Actionable Receiver fails. Commando mode event categories that are processed by the JIT Informative Receiver are:

  • Debit Authorization events
  • Credit Authorization events
  • Authorization Incremental events (limited support)
  • Debit Financial Transaction events
  • Credit Financial Transaction events

OCT Processing

There is a possibility to configure how Original credit transaction (OCT) types are processed. Two options can be selected:

  • Conventional Funds approach
  • Fast Funds approach

The selected approach only impacts processing of dual message OCTs. Single message OCTs are processed in the same way.

Conventional Funds

This is the default OCT processing approach that will be used when enableFastFunds: false is set in your cconnector onfiguration.

In this approach, funds are available after receiving a clearing transaction.

A credit hold is created after receiving an original.credit.authorization actionable request. A credit transaction is executed after receiving a original.credit.authorization.clearing clearing notification.

All reversal instructions decrease or remove a credit hold.

Fast Funds

With Fast Funds enabled, funds are available after receiving an authorization request. Fast Funds can be enabled by setting enableFastFunds: true in your connector configuration.

In this approach, a credit transaction is executed after receiving an original.credit.authorization actionable request.

A credit transaction is also attempted after receiving a original.credit.authorization.clearing clearing notification. If a credit transaction has already been executed, any duplicate transaction is ignored. If enableCustomInformation is set to true in connector setup, then the transaction custom fields are updated with the corresponding information from the clearing notification. If enableAccountCustomInformation is set to true, account custom fields are also filled with the required information. If enableCustomInformation is set to false in connector setup, no custom fields are updated.

All reversal instructions decrease a credit transaction by performing a debit transaction.

The following messages are related to OCT functionality. If the Fast Funds option is enabled, transaction types are processed as described in the Fast Funds column:

Message schemaTransaction typeConventional fundsFast Funds
DMSoriginal.credit.authorizationcreate credit auth holdcreate credit financial transaction
SMSoriginal.credit.auth_plus_capturecreate credit financial transactioncreate credit financial transaction
DMSoriginal.credit.authorization.clearingcreate credit financial transactioncreate credit financial transaction
DMSoriginal.credit.authorization.reversalreverse credit auth holdreverse credit financial transaction
DMSoriginal.credit.authorization.state is DECLINED or CLEAREDreverse credit auth holdreverse credit financial transaction
DMSoriginal.credit.authorization in COMMANDO modecreate credit auth holdcreate credit financial transaction
SMSoriginal.credit.auth_plus_capture in COMMANDO modecreate credit auth holdcreate credit financial transaction

Please be aware Your Integration Consultant can provide a list with all the events handled by the connector and the description of how each event is processed.
More details about Marqeta events and the transaction types that could potentially complete them, can be found in Marqeta’s Core API documentation.

Notifications

The Marqeta connector offers support for sending notifications in cases of business or technical failure in the process.

A Notifications Module folder containing the processes necessary for generating and sending notifications is provided in the connector’s root structure. This module is configurable via the Connector setup process (Mambu + notifications) process found in the Setup & config folder.

The list of events that generate notifications is configurable. Notifications are created in Mambu for all failures relating to any event that involves the movement of money (except for financial transaction reversals).

The notification contains detailed information about the failed transaction. If enableCustomInformation has been set to true when setting up the connector, the notifications will include any information stored in custom fields. notification