Business Flows

Jump to Section

Just-in-Time (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 on 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.

Whether a transaction is temporary or final determines how it moves through various states during its lifecycle. 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 following tables contain details on the types of actionable and informative events processed by the connector.

JIT actionable events

Marqeta event	Event state	Single message	Dual message
`balanceinquiry`	PENDING	✔	✔
`pindebit.balanceinquiry`	PENDING	✔	✔
`authorization`	PENDING		✔
`authorization.incremental`	PENDING		✔
`refund.authorization`	PENDING		✔
`original.credit.authorization`	PENDING		✔
`authorization.quasi.cash`	PENDING		✔
`authorization.atm.withdrawal`	PENDING		✔
`authorization.cashback`	PENDING		✔
`account.funding.authorization`	PENDING		✔
`pindebit.authorization`	PENDING		✔
`pindebit`	COMPLETION	✔
`pindebit.atm.withdrawal`	COMPLETION	✔
`pindebit.cashback`	COMPLETION	✔
`original.credit.auth_plus_capture`	COMPLETION	✔

JIT informative events

Marqeta event	Event state	Single message	Dual message
`authorization.clearing.representment`	COMPLETION		✔
`authorization.clearing`	COMPLETION		✔
`authorization.clearing.atm.withdrawal`	COMPLETION		✔
`authorization.clearing.quasi.cash`	COMPLETION		✔
`authorization.clearing.cashback`	COMPLETION		✔
`authorization.standin`	PENDING		✔
`pindebit.authorization.clearing`	COMPLETION		✔
`authorization.clearing.chargeback`	COMPLETION		✔
`authorization.clearing.chargeback.completed`	COMPLETION		✔
`pindebit.chargeback`	COMPLETION	✔
`pindebit.chargeback.completed`	COMPLETION	✔
`pindebit.refund`	COMPLETION	✔
`pindebit.reversal`	COMPLETION		✔
`account.funding.authorization.clearing`	COMPLETION		✔
`refund.authorization.clearing`	COMPLETION		✔
`original.credit.authorization.clearing`	COMPLETION		✔
`refund`	COMPLETION		✔
`pindebit.refund.reversal`	COMPLETION		✔
`original.credit.auth_plus_capture.reversal`	COMPLETION		✔
`authorization`	DECLINED CLEARED		✔
`authorization.atm.withdrawal`	DECLINED CLEARED		✔
`authorization.quasi.cash`	DECLINED CLEARED		✔
`refund.authorization`	DECLINED CLEARED		✔
`original.credit.authorization`	DECLINED CLEARED		✔
`authorization.cashback`	DECLINED CLEARED		✔
`account.funding.authorization`	DECLINED CLEARED		✔
`pindebit.authorization`	DECLINED CLEARED		✔
`authorization.incremental`	DECLINED		✔
`authorization.reversal`	CLEARED		✔
`authorization.advice`	PENDING		✔
`authorization.reversal.issuerexpiration`	CLEARED		✔
`pindebit.authorization.reversal.issuerexpiration`	CLEARED		✔
`original.credit.authorization.reversal`	CLEARED		✔
`refund.authorization.reversal`	CLEARED		✔
`account.funding.authorization.reversal`	CLEARED		✔
`authorization.clearing.chargeback.reversal`	CLEARED		✔
`pindebit.chargeback.reversal`	CLEARED		✔
`authorization` commando mode	PENDING		✔
`authorization.atm.withdrawal` commando mode	PENDING		✔
`authorization.cashback` commando mode	PENDING		✔
`authorization.quasi.cash` commando mode	PENDING		✔
`pindebit.authorization` commando mode	PENDING		✔
`account.funding.authorization` commando mode	PENDING		✔
`account.incremental` commando mode	PENDING		✔
`pindebit` commando mode	PENDING	✔
`pindebit.atm.withdrawal` commando mode	PENDING	✔
`pindebit.cashback` commando mode	PENDING	✔
`original.credit.auth_plus_capture` commando mode	PENDING	✔
`pindebit`	DECLINED	✔
`pindebit.atm.withdrawal`	DECLINED	✔
`pindebit.cashback`	DECLINED	✔
`original.credit.auth_plus_capture`	DECLINED	✔

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: type, state, token, card_token, amount, and currency_code. The jit_funding object is checked only for clearing transactions that have funding source type programgateway.

The type and state parameters are later used in the routing logic, which is a decision related to the transaction type that needs to be posted in Mambu.

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, amount, and currency_code parameters.
If the gpa_order_unload.jit_funding object is not present, batch validations are skipped and the event is ignored.

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
Declined single message debit and credit financial transactions which trigger the reversal of 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 connector configuration.

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 schema	Transaction type	Conventional funds	Fast Funds
DMS	`original.credit.authorization`	create credit auth hold	create credit financial transaction
SMS	`original.credit.auth_plus_capture`	create credit financial transaction	create credit financial transaction
DMS	`original.credit.authorization.clearing`	create credit financial transaction	create credit financial transaction
DMS	`original.credit.authorization.reversal`	reverse credit auth hold	reverse credit financial transaction
DMS	`original.credit.authorization.state` is `DECLINED` or `CLEARED`	reverse credit auth hold	reverse credit financial transaction
DMS	`original.credit.authorization` in COMMANDO mode	create credit auth hold	create credit financial transaction
SMS	`original.credit.auth_plus_capture` in COMMANDO mode	create credit auth hold	create 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.

Data Extraction Connectors