Skip to main content

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.
To set up Gateway JIT Funding, you will need:
  • 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.
The Marqeta platform and your system exchange the following messages:
  • 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.
  • 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.

JIT Funding request object

The jit_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.
Depending on user setup, one of the fields below will be present:
  • 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
{
  "gpa_order": {
    "jit_funding": {
      "token": "string",
      "method": "pgfs.authorization",
      "amount": "30.00",
      "original_jit_funding_token": "string",
      "user_token": "**MASKED**",
      "acting_user_token": "**MASKED**"
    }
  }
}

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 code 200.
  • deny — Funding request denial via HTTP response code 402.
JIT Funding response object details are outlined below.
  • 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
{
  "jit_funding": {
    "token": "JIT A",
    "method": "pgfs.authorization",
    "user_token": "USER A",
    "amount": 128.99,
    "memo": "account_inactive",
    "tags": "tag here",
    "decline_reason": "TRANSACTION_NOT_PERMITTED",
    "original_jit_funding_token": "JIT A"
  }
}

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 MethodApplicable Transaction Type
pgfs.authorization

Impact to Cardholder Balance:
Negative
authorization

authorization.quasi.cash

authorization.cashback

authorization.atm.withdrawal

account.funding.authorization
pgfs.authorization.incremental

Impact to Cardholder Balance:
Negative
authorization.incremental
pgfs.original.credit.authorization

Impact to Cardholder Balance:
Positive
original.credit.authorization
pgfs.balanceinquiry

Impact to Cardholder Balance:
N/A
balanceinquiry
pgfs.refund.authorization

Impact 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 MethodTransaction Type Applicable To
pgfs.authorization.capture

pgfs.force_capture

Impact to Cardholder Balance:
Negative
authorization.clearing

authorization.clearing.atm.withdrawal

authorization.clearing.quasi.cash

authorization.clearing.cashback

account.funding.authorization.clearing
pgfs.reversal

Impact to Cardholder Balance:
Positive
authorization.reversal

authorization.reversal.issuerexpiration

authorization.advice
pgfs.original.credit.authorization.reversal

Impact to Cardholder Balance:
Negative
original.credit.authorization.reversal

authorization.reversal.issuerexpiration
pgfs.original.credit.authorization.clearing

Impact to Cardholder Balance:
Positive
original.credit.authorization.clearing
pgfs.refund

Impact to Cardholder Balance:
Positive
refund

refund.authorization.clearing
pgfs.refund.authorization.reversal

Impact to Cardholder Balance:
Negative
refund.authorization.reversal

authorization.reversal.issuerexpiration
For more information, see Ledger-impacting transaction events.

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.authorization JIT method.
  • Negative impact to cardholder balance.
An actionable event can be authorized for a lower amount when 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 PENDING state until they are fully cleared or reversed. Please refer to the transaction lifecycle for more details.
JSON
{
  "type": "authorization",
  "state": "PENDING",
  "token": "TRANSACTION A",
  "amount": "50.00",
  "gpa_order": {
    "jit_funding": {
      "token": "JIT B",
      "method": "pgfs.authorization",
      "amount": "50.00"
    }
  }
}

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.reversal JIT method.
  • Positive impact to cardholder balance.
Payment reversal can be used to fully or partially reverse the authorization hold of a transaction. Common reasons why payment reversals occur include:
  • 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
{
  "type": "authorization.reversal",
  "state": "CLEARED",
  "token": "TRANSACTION C",
  "preceding_related_transaction_token": "TRANSACTION A",
  "amount": "1.00",
  "gpa_order": {
    "jit_funding": {
      "token": "JIT C",
      "method": "pgfs.authorization.reversal",
      "amount": "1.00",
      "original_jit_funding_token": "JIT A"
    }
  }
}

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.reversal JIT method.
  • Impact to cardholder balance depends on the linked transaction.
Expiration hold is adjusted depending on specific criteria:
  • 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).
Issuer expiration can be used to expire any type of authorization, including credit (authorization) and debit (refund.authorization).
  • jit_funding.method refers to the funding type.
    • pgfs.refund.authorization.reversal refers to the expiration of refund.authorization.
    • pgfs.authorization.reversal refers to the expiration of authorization.
The following diagram illustrates state transitions during an example of issuer expiration.
Issuer expiration
JSON
{
  "type": "authorization.reversal.issuerexpiration",
  "state": "CLEARED",
  "token": "TRANSACTION C",
  "preceding_related_transaction_token": "TRANSACTION A",
  "amount": "1.00",
  "gpa_order": {
    "jit_funding": {
      "token": "JIT C",
      "method": "pgfs.authorization.reversal",
      "amount": "1.00",
      "original_jit_funding_token": "JIT A"
    }
  }
}

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.incremental JIT method.
  • Negative impact to cardholder balance.
Incremental authorization increases the amount of a previous authorization by holding additional funds without replacing the original authorization. It can be received multiple times for a single authorization. For each incremental request, Marqeta will:
  • Request approval for additional funds via the JIT gateway.
    • If approved, the amount of funds held will increase.
  • Link incremental authorization to original authorization.
The following diagram illustrates state transitions during an example of incremental authorization.
Incremental authorization
JSON
{
  "type": "authorization.incremental",
  "state": "PENDING",
  "token": "TRANSACTION B",
  "preceding_related_transaction_token": "TRANSACTION A",
  "amount": "50.00",
  "gpa_order": {
    "jit_funding": {
      "token": "JIT B",
      "method": "pgfs.authorization.incremental",
      "amount": "50.00",
      "original_jit_funding_token": "JIT A"
    }
  }
}

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.reversal JIT method.
  • Positive impact to cardholder balance.
The following diagram illustrates state transitions during an example of authorization advice.
Authorization advice
JSON
{
  "type": "authorization.advice",
  "state": "PENDING",
  "token": "TRANSACTION B",
  "preceding_related_transaction_token": "TRANSACTION A",
  "amount": "70.00",
  "gpa_order": {
    "jit_funding": {
      "token": "JIT B",
      "method": "pgfs.authorization.reversal",
      "amount": "30.00",
      "original_jit_funding_token": "JIT A"
    }
  }
}

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_capture JIT method.
  • Negative impact to cardholder balance.
  • Completion event.
Through Marqeta’s enhanced finding logic, Marqeta matches 99.5% of clearing events back to their original authorization. They are often offline transactions (no online authorization). Marqeta is mandated to process any clearings regardless of whether they link to an original authorization. If linked, the authorization method is 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.
Authorization clearing
JSON
{
  "type": "authorization.clearing",
  "state": "COMPLETION",
  "token": "TRANSACTION B",
  "preceding_related_transaction_token": "TRANSACTION A",
  "amount": "50.00",
  "gpa_order": {
    "jit_funding": {
      "token": "JIT B",
      "method": "pgfs.authorization.capture",
      "amount": "50.00",
      "original_jit_funding_token": "JIT A"
    }
  },
  "batch_number": "**MASKED**",
  "acquirer_reference_data": "**MASKED**"
}

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_capture JIT method.
  • Negative impact to cardholder balance.
  • Completion event.
The following diagram illustrates state transitions during an example of force post clearing.
Force post clearing
JSON
{
  "type": "authorization.clearing",
  "state": "COMPLETION",
  "token": "TRANSACTION A",
  "amount": "50.00",
  "gpa_order": {
    "jit_funding": {
      "token": "JIT A",
      "method" : "pgfs.force_capture",
      "amount": "50.00",
    }
  },
  "batch_number": "**MASKED**",
  "acquirer_reference_data": "**MASKED**"
}

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.refund JIT method.
  • Positive impact to cardholder balance.
  • Does not link to the original authorization.
The following diagram illustrates state transitions during an example of refund.
Refund
JSON
{
  "type": "refund",
  "state": "COMPLETION",
  "token": "TRANSACTION C",
  "amount": "70.00",
  "gpa_order_unload": {
    "jit_funding": {
      "token": "JIT C",
      "method": "pgfs.refund",
      "amount": "70.00"
    }
  }
}

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.authorization JIT method.
  • Positive impact to cardholder balance.
Refund Clearing is an informative event with the following details:
  • Sent via webhooks.
  • pgfs.refund JIT method.
  • Positive impact to cardholder balance.
Online refunds, like standard refunds, contain no reference to the original purchase authorization. The primary purpose of the return authorization message is to provide information to a cardholder that a credit is being processed. Due to being information minimal, checks are required during the approval process.
Important
A cardholder’s available balance should not be increased upon receipt of the refund.authorization event. Instead, it should be shown to the cardholder as a pending item in the online transaction’s history. Your system should not allow the cardholder to spend the credited amount until the clearing event has been processed.
In the event of a reversal, either merchant reversal or Marqeta expiration, you would simply remove the pending item on the online transaction’s history. A cardholder’s available balance should not reflect adjustments until after the clearing event has been completed. The following diagram illustrates state transitions during an example of online refund.
Online refund
JSON
{
  "type": "refund.authorization",
  "state": "PENDING",
  "token": "TRANSACTION A",
  "amount": "70.00",
  "gpa_order_unload": {
    "jit_funding": {
      "token": "JIT A",
      "method": "pgfs.refund.authorization",
      "amount": "70.00"
    }
  }
}
JSON
{
  "type": "refund.authorization.clearing",
  "state": "COMPLETION",
  "amount": "70.00",
  "preceding_related_transaction_token": "TRANSACTION B",
  "gpa_order_unload": {
    "jit_funding": {
      "token": "JIT B",
      "method": "pgfs.refund",
      "amount": 70.00,
      "original_jit_funding_token": "JIT A"
    }
  }
}

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.authorization JIT method.
  • Positive impact to cardholder balance.
OCT Clearing is an informative event with the following details:
  • Sent via webhooks.
  • pgfs.original.credit.authorization.clearing JIT method.
  • Positive impact to cardholder balance.
  • Transaction model includes the original_credit object.
JSON
{
  "type": "original.credit.authorization",
  "state": "PENDING",
  "token": "TRANSACTION A",
  "amount": "100.00",
  "gpa_order_unload": {
    "jit_funding": {
      "token": "JIT A",
      "method": "pgfs.original.credit.authorization",
      "amount": "100.00"
    }
  },
  "original_credit": {
    "transaction_type": "person_to_person",
    "funding_source": "credit",
    "sender_name": "XXXX"
  }
}
JSON
{
  "type": "original.credit.authorization.clearing",
  "state": "COMPLETION",
  "token": "TRANSACTION B",
  "preceding_related_transaction_token": "TRANSACTION A",
  "amount": "100.00",
  "gpa_order_unload": {
    "jit_funding": {
      "token": "JIT B",
      "method": "pgfs.original.credit.authorization.clearing",
      "amount": "100.00",
      "original_jit_funding_token": "JIT A"
    }
  }
}

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.authorization JIT method.
  • Negative impact to cardholder balance.
AFT Clearing is an informative event with the following details:
  • Sent via webhooks.
  • pgfs.authorization.clearing JIT method.
  • Negative impact to cardholder balance.
  • Transaction model includes the account_funding object.
JSON
{
  "type": "account.funding.authorization",
  "state": "PENDING",
  "token": "TRANSACTION A",
  "amount": "100.00",
  "gpa_order": {
    "jit_funding": {
      "token": "JIT A",
      "method": "pgfs.authorization",
      "amount": "100.00"
    }
  },
  "account_funding": {
    "transaction_type": "PERSON_TO_PERSON"
  }
}
JSON
{
  "type": "account.funding.authorization.clearing",
  "state": "COMPLETION",
  "token": "TRANSACTION B",
  "preceding_related_transaction_token": "TRANSACTION A",
  "amount": "100.00",
  "gpa_order": {
    "jit_funding": {
      "token": "JIT B",
      "method": "pgfs.authorization.capture",
      "amount": "100.00",
      "original_jit_funding_token": "JIT A"
    }
  }
}

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.authorization JIT method.
  • Negative impact to cardholder balance.
Quasi Cash Clearing is an informative event with the following details:
  • Sent via webhooks.
  • pgfs.authorization.capture JIT method.
  • Negative impact to cardholder balance.
Quasi-cash transactions are primarily based on merchant category codes (MCCs). The following are typical MCCs and their descriptions:
  • 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)
The optional transaction type must be enabled at the Marqeta card product level.
JSON
{
 "token": "TRANSACTION A",
 "type": "authorization.quasi.cash",
  "state": "PENDING",
  "gpa_order": {
    "jit_funding": {
      "method": "pgfs.authorization",
      "amount": 10.00
    }
  },
  "amount": 10.00
}
JSON
{
  "type": "authorization.clearing.quasi.cash",
  "state": "COMPLETION",
  "token": "TRANSACTION B",
  "preceding_related_transaction_token": "TRANSACTION A",
  "gpa_order": {
    "jit_funding": {
      "method": "pgfs.authorization.capture",
      "amount": 10.00
    }
  },
  "amount": 10.00
}

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.authorization JIT method.
  • Negative impact to cardholder balance.
ATM Withdrawal Clearing is an informative event with the following details:
  • Sent via webhooks.
  • pgfs.authorization.capture JIT method.
  • Negative impact to cardholder balance.
The optional transaction type must be enabled at the network BIN level and the Marqeta card product level. It can be used to force offline PIN sync, after PIN reset, to sync online Marqeta PIN and offline chip PIN.
JSON
{
  "token": "TRANSACTION A",
  "type": "authorization.atm.withdrawal",
  "state": "PENDING",
  "gpa_order": {
    "jit_funding": {
      "method": "pgfs.authorization",
      "amount": 40.00
    }
  },
  "amount": 40.00
}
JSON
{
  "token": "TRANSACTION B",
  "type" : "authorization.clearing.atm.withdrawal",
  "state" : "COMPLETION",
  "preceding_related_transaction_token": "TRANSACTION A",
  "gpa_order" : {
    "jit_funding" : {
      "method" : "pgfs.authorization.capture",
      "amount" : 40.00
    }
  },
  "amount" : 40.00
}

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.balanceinquiry JIT method.
  • No impact to cardholder balance.
The optional transaction type must be enabled at the network BIN level and the Marqeta card product level. The 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
{
  "type": "balanceinquiry",
  "state": "COMPLETION",
  "gpa_order": {
    "jit_funding": {
      "method": "pgfs.balanceinquiry",
      "amount": 0.00
    }
  },
  "amount": 0.00
}
JSON
{
  "jit_funding": {
    "token": "45831493-571d-4ded-8376-315201210dbf",
    "method": "pgfs.balanceinquiry",
    "amount": 0,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "available_balance": 1206.45
      }
    }
  }
}

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:
ResponsibilityPowered ByManaged By
Receive and respond to actionable JIT Funding requests within three secondsYouYou
Validate transactionsMarqetaMarqeta
Process informative webhook events, such as clearings and reversalsYouYou
Limit transactional spending according to the velocity controls you specifyMarqetaMarqeta
Maintain and manage customer balances and fund movementsYouYou
Process transactions and provide you with transaction webhooksMarqetaMarqeta