Gateway Just-in-Time Funding
Just-in-Time (JIT) Funding is a method of automatically funding an account in real time during the transaction process. With Gateway JIT Funding, your system participates in the funding approval process, enabling you to have a high level of control over which transactions are successfully approved. For more information about this option, see Gateway JIT Funding.Note
Alternatively, with Managed JIT Funding, you define when, where, and how much a cardholder can spend with their card, but you cannot allow or deny individual transactions as they happen. To learn more, see Managed JIT Funding.
Alternatively, with Managed JIT Funding, you define when, where, and how much a cardholder can spend with their card, but you cannot allow or deny individual transactions as they happen. To learn more, see Managed JIT Funding.
- A funding source configured for JIT Funding. The funding source defines the endpoint on your system where the Marqeta platform sends funding requests.
- A card product configured for JIT Funding associated with the funding source above.
-
JIT Funding requests are actionable messages sent by Marqeta requesting permission to fund a transaction.
- Your system makes a decision to allow or deny the funds based on your own business rules. These synchronous messages request permission to fund a specific transaction or to answer a balance inquiry.
-
JIT Funding responses are sent by your gateway to the Marqeta platform in response to a funding request.
-
To approve, set the HTTP response code to
200 OK, including a correctly formatted response body. -
To deny, set the HTTP response code to
402 Request Failed, including a correctly formatted response body.
-
To approve, set the HTTP response code to
-
JIT Funding notifications are transaction event messages sent by Marqeta to your webhook endpoint.
- These asynchronous messages contain the entire transaction and inform you about its ultimate outcome. They are different from your gateway endpoint.
- If JIT Funding is set up, the messages should confirm that the requested action was taken.
- If JIT Funding is not set up, the messages should confirm the ledger amendment.
Note
When you have finalized your build in the sandbox environment, Marqeta can perform a review to make sure that you have covered all scenarios relevant to your program and that your JIT Funding responses are in the correct format and are parsed correctly by the Marqeta platform. This optional requirement can provide confidence in your testing in the sandbox and is completed just before production credentials are provided.
When you have finalized your build in the sandbox environment, Marqeta can perform a review to make sure that you have covered all scenarios relevant to your program and that your JIT Funding responses are in the correct format and are parsed correctly by the Marqeta platform. This optional requirement can provide confidence in your testing in the sandbox and is completed just before production credentials are provided.
JIT Funding request object
Thejit_funding object contains information about the funding event, including the associated user token and transaction amount. The method field indicates the type of transaction. JIT Funding request object details are outlined below.
-
method— Determines the funding action required. For example, hold funds, release funds, and capture funds. -
amount— Indicates the amount to hold, reverse, or clear. -
original_jit_funding_token— References the original JIT Funding call if the transaction consists of multiple JIT Funding calls. -
acting_user_token— Indicates the token of the cardholder conducting the transaction. This is always the user associated with the card.
-
user_token— Indicates the top-level user token. In most cases, this will be the cardholder who is making the transaction. However, in parent-child setups, this will be the parent. -
business_token— Indicates the token of the business that the acting user is associated with.
JSON
JIT Funding response object
Your JIT Funding gateway must respond to each JIT Funding request by either approving or denying the request. You must include all required fields, regardless of whether you approve or deny the transaction. Balance inquiries require an additional balance object. To approve or decline a transaction, return one of these response codes:-
approve— Funding request approval via HTTP response code200. -
deny— Funding request denial via HTTP response code402.
-
method— The method must match the one found in the matching request. -
tags— A comma-delimited list of tags used to tag internal error codes. -
memo— Free-form comments included in the transaction data for authorization and authorization completion transactions (no personally identifiable information). -
decline_reason— A descriptive reason for declining the transaction to ensure that Marqeta reports the correct response code to the network based on your decline reason. -
original_jit_funding_token— The token of the first associated JIT Funding message. This token enables you to correlate related JIT Funding messages. This field is not included in the first of any set of related messages.
JSON
Ledger management
JIT Funding Gateway
Actionable messages are sent by the Marqeta platform to an endpoint on your system called the JIT Funding Gateway. These synchronous messages request permission to fund a specific transaction. The details of these messages are outlined below.| JIT Funding Method | Applicable Transaction Type |
|---|---|
pgfs.authorizationImpact to Cardholder Balance: Negative | authorizationauthorization.quasi.cashauthorization.cashbackauthorization.atm.withdrawalaccount.funding.authorization |
pgfs.authorization.incrementalImpact to Cardholder Balance: Negative | authorization.incremental |
pgfs.original.credit.authorizationImpact to Cardholder Balance: Positive | original.credit.authorization |
pgfs.balanceinquiryImpact to Cardholder Balance: N/A | balanceinquiry |
pgfs.refund.authorizationImpact to Cardholder Balance: Positive | refund.authorization |
Webhooks
Informative messages are sent by the Marqeta platform to your webhook endpoint and are separate from the JIT gateway. These asynchronous messages contain the entire transaction and inform you about events sent by the network, such as clearings and reversals. The details of these messages are outlined below.| JIT Funding Method | Transaction Type Applicable To |
|---|---|
pgfs.authorization.capturepgfs.force_captureImpact to Cardholder Balance: Negative | authorization.clearingauthorization.clearing.atm.withdrawalauthorization.clearing.quasi.cashauthorization.clearing.cashbackaccount.funding.authorization.clearing |
pgfs.reversalImpact to Cardholder Balance: Positive | authorization.reversalauthorization.reversal.issuerexpirationauthorization.advice |
pgfs.original.credit.authorization.reversalImpact to Cardholder Balance: Negative | original.credit.authorization.reversalauthorization.reversal.issuerexpiration |
pgfs.original.credit.authorization.clearingImpact to Cardholder Balance: Positive | original.credit.authorization.clearing |
pgfs.refundImpact to Cardholder Balance: Positive | refundrefund.authorization.clearing |
pgfs.refund.authorization.reversalImpact to Cardholder Balance: Negative | refund.authorization.reversalauthorization.reversal.issuerexpiration |
Authorization
An authorization is an approval of a funding request. If the customer details are correct, the Marqeta platform moves funds from the funding source into the cardholder’s account. The details of the actionable event include:- Sent via JIT gateway.
-
pgfs.authorizationJIT method. - Negative impact to cardholder balance.
partial_approval_capable is set to true. It must also be allowed on the card product level.
This is useful for automated fuel dispenser (AFD) scenarios such as MCC 5542. In these transactions, padding is applied up to the value of the UP_TO_LIMIT field (e.g., £100) if the transaction amount is equal to any of the following values:
- Exactly £0 GBP
- Exactly £1 GBP
- Exactly 0 units or 1 unit in the local transaction currency
Note
Transactions will remain in the
Transactions will remain in the
PENDING state until they are fully cleared or reversed. Please refer to the transaction lifecycle for more details.JSON
Payment reversal
A payment reversal occurs when the funds held against a cardholder for a transaction are returned to the cardholder’s available spending balance. This can be initiated by the cardholder, the merchant, the issuing bank, the acquiring bank, or the card association. An authorization hold is placed for the amount of the transaction. Before the merchant receives the funds, the cardholder cannot access the held amount. To release the hold, an authorization reversal can be initiated before the transfer is complete. This cancels the sale and prevents the transaction from going through. The details of the informative event include:- Sent via webhooks.
-
pgfs.authorization.reversalJIT method. - Positive impact to cardholder balance.
- The merchant requested the wrong dollar amount when submitting a transaction.
- The transaction was accidentally processed more than once.
- The item purchased is backordered or out of stock.
- The customer decided against the item after ordering.
JSON
Issuer expiration
Issuer expiration reverses or drops a pending authorization due to elapsed time. It is initiated by Marqeta and configurable by merchant category code (MCC) groups. This expiration identifies that the authorization has been pending for an extended amount of time and is unlikely to clear. The details of the informative event include:- Sent via webhooks.
-
pgfs.authorization.reversal/pgfs.authorization.refund.reversalJIT method. - Impact to cardholder balance depends on the linked transaction.
- Car rental and lodging hold expirations are 30 days by default (configurable using MCC group).
- Automated fuel dispensers expire three days after receiving advice (for example, AFD, MCC 5542).
- Authorizations less than one will be reversed within three days of the authorization. Otherwise, the authorization hold time is eight days before being reversed (default is configurable by Marqeta).
authorization) and debit (refund.authorization).
-
jit_funding.methodrefers to the funding type.-
pgfs.refund.authorization.reversalrefers to the expiration ofrefund.authorization. -
pgfs.authorization.reversalrefers to the expiration ofauthorization.
-
JSON
Incremental authorization
Incremental authorizations are used to make ongoing increases to the original authorized transaction amount without the presence of the payment card. They can be used to add to an existing transaction or to allow for a revised estimate of what the cardholder may spend. These revisions represent additions to previously authorized amounts and do not replace the original authorization. The details of the actionable event include:- Sent via JIT gateway.
-
pgfs.authorization.incrementalJIT method. - Negative impact to cardholder balance.
-
Request approval for additional funds via the JIT gateway.
- If approved, the amount of funds held will increase.
- Link incremental authorization to original authorization.
JSON
Authorization advice
Authorization advice is an adjustment to reduce the hold of funds from the original authorization. The majority of use cases are automated fuel dispensers (AFDs), which consist of an initial authorization followed by advice to correct the amount of the authorization. The advice replaces the existing authorization hold with a new hold amount. The details of the informative event include:- Sent via webhooks.
- Reverses the difference in authorization hold.
-
pgfs.authorization.reversalJIT method. - Positive impact to cardholder balance.
JSON
Authorization clearing
Authorization clearing is the process of finalizing the hold on funds and posting the transaction on the cardholder’s account. This process is triggered in batches by the merchant’s capture request. Clearings provide the amounts to be debited from issuers and credited to acquirers. The details of the informative event include:- Sent via webhooks.
-
pgfs.authorization.capture/pgfs.force_captureJIT method. - Negative impact to cardholder balance.
- Completion event.
pgfs.authorization.capture. If not linked, the authorization method is pgfs.force_capture. For more information, see Force post clearing.
The following diagram illustrates state transitions during an example of authorization clearing.
JSON
Force post clearing
Force post clearing is the process of finalizing the hold on funds and posting the transaction on the cardholder’s account. This process is triggered in batches by the merchant’s capture request. Clearings provide the amounts to be debited from issuers and credited to acquirers. The details of the informative event include:- Sent via webhooks.
-
pgfs.force_captureJIT method. - Negative impact to cardholder balance.
- Completion event.
JSON
Refund
A refund occurs when you have charged a payer and need to cancel the payment to return the funds to the payer. The funds will be returned through the payment method the payer initially used to make the payment. The details of the informative event include:- Sent via webhooks.
-
pgfs.refundJIT method. - Positive impact to cardholder balance.
- Does not link to the original authorization.
JSON
Online refund
An online refund is a credit event which firstly requires authorization. The networks mandate that authorizations for refunds should be completed. Refund Authorization is an actionable event with the following details:- Sent via JIT gateway.
-
pgfs.refund.authorizationJIT method. - Positive impact to cardholder balance.
- Sent via webhooks.
-
pgfs.refundJIT method. - Positive impact to cardholder balance.
JSON
JSON
Original credit transaction
An Original Credit Transaction (OCT) is a credit to a users account. For example, this could be a cashback scheme, money back from a delayed train, or a money transfer into an account from another person. OCT Authorization is an actionable event with the following details:- Sent via JIT gateway.
-
pgfs.original.credit.authorizationJIT method. - Positive impact to cardholder balance.
- Sent via webhooks.
-
pgfs.original.credit.authorization.clearingJIT method. - Positive impact to cardholder balance.
-
Transaction model includes the
original_creditobject.
JSON
JSON
Account funding transaction
An Account Funding Transaction (AFT) is a transaction used to pull funds from a card account in order to fund an Original Credit Transaction (OCT) to a different account, which can belong to the cardholder or another person. AFT Authorization is an actionable event with the following details:- Sent via JIT gateway.
-
pgfs.authorizationJIT method. - Negative impact to cardholder balance.
- Sent via webhooks.
-
pgfs.authorization.clearingJIT method. - Negative impact to cardholder balance.
-
Transaction model includes the
account_fundingobject.
JSON
JSON
Authorization quasi cash
Quasi-cash transactions represent the purchase of foreign currencies or items that may be convertible to cash. Examples include casino chips, cryptocurrencies, money orders, lottery tickets, and traveler’s checks. Quasi Cash Authorization is an actionable event with the following details:- Sent via JIT gateway.
-
pgfs.authorizationJIT method. - Negative impact to cardholder balance.
- Sent via webhooks.
-
pgfs.authorization.captureJIT method. - Negative impact to cardholder balance.
- 7802 – Government-licensed horse/dog racing
- 7995 – Betting, lottery tickets, casino gambling chips, off-track betting, race tracks
- 4829 – Money order / wire transfer
- 6050 – Quasi cash / customer financial institution
- 6051 – Non-financial institution cryptocurrency, foreign currency, traveler’s check
- 7801 – Government-licensed online casinos (online gambling)
JSON
JSON
ATM withdrawal
An automated teller machine (ATM) withdrawal is the mechanism by which a cardholder can withdraw money from their account. These event types are distinct in the Marqeta system, in order to allow you to monitor and treat them independently if required. ATM Withdrawal Authorization is an actionable event with the following details:- Sent via JIT gateway.
-
pgfs.authorizationJIT method. - Negative impact to cardholder balance.
- Sent via webhooks.
-
pgfs.authorization.captureJIT method. - Negative impact to cardholder balance.
JSON
JSON
ATM balance inquiry
An automated teller machine (ATM) balance inquiry is the mechanism by which a cardholder can gain insight into their account balance directly from the ATM. These event types are distinct in the Marqeta system, in order to allow you to monitor and treat them independently if required. ATM Balance Inquiry details include:- Sent via JIT gateway.
-
pgfs.balanceinquiryJIT method. - No impact to cardholder balance.
balances object must be returned in the JIT Funding response, which will be displayed to the cardholder on the ATM screen. This can be used to force offline PIN sync, after PIN reset, to sync online Marqeta PIN and offline chip PIN.
JSON
JSON
Just-in-Time Funding responsibilities
If you offer a card program in Europe, there are several responsibilities that you and Marqeta maintain. These responsibilities include:| Responsibility | Powered By | Managed By |
|---|---|---|
| Receive and respond to actionable JIT Funding requests within three seconds | You | You |
| Validate transactions | Marqeta | Marqeta |
| Process informative webhook events, such as clearings and reversals | You | You |
| Limit transactional spending according to the velocity controls you specify | Marqeta | Marqeta |
| Maintain and manage customer balances and fund movements | You | You |
| Process transactions and provide you with transaction webhooks | Marqeta | Marqeta |