Configuring Gateway JIT Funding
The Marqeta platform enables you to fund accounts at transaction time using your system to make funding decisions. Your system receives funding requests and approves or denies them using your own business rules. For the scenario presented in this tutorial, you will use a mock endpoint to simulate your system’s participation in the funding approval process.
A card configured for Gateway JIT Funding requires a card product associated with a program gateway funding source.
Note
The sandbox environment allows you to create and configure the resources required for a Gateway JIT Funding setup. To implement these configurations in a production environment, contact your Marqeta representative.At the end of this guide, you should understand:
-
The role of the program gateway funding source in Gateway JIT Funding.
-
How your system participates in the funding approval process.
-
How to create a card for an account funded by Managed JIT Funding.
-
How to simulate a transaction with a card.
Prerequisites
Copy section link
-
Read the Core API Quick Start.
Concepts
Copy section link
JIT Funding
Copy section link
JIT Funding automates the loading of funds into accounts in real time during the transaction process. In a Gateway JIT Funding setup, the Marqeta platform and your system both participate in authorization decisions. Funds are drawn from the program gateway funding source defined by the card product.
The Marqeta platform and your system exchange messages of the following types:
-
JIT Funding requests are actionable messages sent by the Marqeta platform requesting permission to fund a specific transaction.
-
JIT Funding responses are sent by your gateway to the Marqeta platform in response to a funding request.
-
JIT Funding notifications are transaction event messages sent by the Marqeta platform to your webhook endpoint (not your gateway endpoint). These asynchronous messages contain the entire transaction and inform you about its ultimate outcome.
For more information about JIT Funding, see About Just-in-Time Funding.
The program gateway funding source
Copy section link
A program gateway funding source represents a bank account from which funds are drawn for JIT-funded transactions. In the sandbox environment, you can create a program gateway funding source that simulates funds for your test transactions. In a production environment, you must work with a Marqeta representative to define the bank account from which the program gateway funding source draws funds.
Note
If you are using a third-party service to collect user funds, Marqeta and the issuing bank require specific reporting to ensure compliance with all rules and regulations. Contact your Marqeta representative for more information.For a complete description of the
Card product configuration
Copy section link
A card product defines attributes and behaviors for a set of cards. Each card product has a single funding source, which funds all transactions conducted using an associated card. Gateway JIT Funding setups require you to create a card product associated with a program gateway funding source.
Note
You can create and configure card products in the sandbox environment. To create a new card product for production, contact your Marqeta representative for more information.
Your gateway endpoint
Copy section link
To participate in Gateway JIT Funding decisions, your system must respond to requests sent by the Marqeta platform. Your system can respond to a funding request in the following ways:
-
To approve, set the HTTP response code to
200 OK. -
To deny, set the HTTP response code to
402 Request Failed.
For more information on handling Gateway JIT Funding events, see Gateway JIT Funding Messages.
Your webhook endpoint
Copy section link
To handle informative Gateway JIT Funding messages, your system must include an endpoint for receiving event notifications. Within seconds of each transaction, the Marqeta platform sends webhook notifications to your endpoint to enable you to track requests, maintain balances, and resolve timeout issues.
Your system must respond to each informative JIT Funding request using the
Tutorial
Copy section link
The following tutorial walks you through creating and testing the resources required for a Gateway JIT Funding setup. In this scenario, you will set up a mock endpoint for receiving JIT Funding messages, create a card configured for Gateway JIT Funding, simulate a transaction, and review the transaction record.
Some steps include a code block with a JSON-formatted sample message body. To follow along with the tutorial, you must sign in to Marqeta.com. For each step, copy the code sample and paste it into the body field of the provided API Explorer widget. Replace any placeholder text with your sample data, then click Submit Request.
Step 1 — Set up a mock endpoint
Copy section link
In a production environment, a Gateway JIT Funding setup requires your system to have two endpoints configured: one to act as a gateway and participate in JIT Funding requests, and another to receive notifications. This tutorial, however, does not require you to set up endpoints on your system.
To create a mock gateway endpoint, go to https://beeceptor.com/ (or another mock endpoint service) and create a mock endpoint. Save the mock endpoint’s URL for use in later steps.
For more information on JIT Funding messages, see Gateway JIT Funding Messages.
Step 2 — Create a program gateway funding source
Copy section link
To define the bank account from which funds are drawn for transactions, create a program gateway funding source.
Send a
Populate the
Step 3 — Create a card product
Copy section link
To define attributes and behaviors for a set of cards, create a card product. The
Send a
Step 4 — Create a user
Copy section link
Before you create a new card, you must create a user who will own the card.
Send a
Step 5 — Create a card
Copy section link
Send a
Step 6 — Simulate a transaction
Copy section link
Now that you have created a card, you can use it to simulate a transaction.
Send the following
Note
For more information on the
Step 7 — Receive the JIT Funding request on your gateway
Copy section link
Go to your mock endpoint URL. It should receive two messages. The first message contains the JIT Funding request. The second message contains the notification sent after the funding decision is made. Because you cannot reply to the JIT Funding request using your mock endpoint, the JIT Funding attempt fails no matter what. For the purposes of this scenario, you can ignore the second message.
The following is a snippet of the JIT Funding request.
Step 8 — Return a JIT Funding response
Copy section link
In a production environment, your gateway endpoint programmatically returns a JIT Funding response and approves or denies the funding request.
A complete JIT Funding response includes the following elements:
-
The appropriate HTTP response code (
200 OKor402 Request Failed). -
The token of the incoming JIT Funding request.
-
The method (or type) of the transaction being funded.
-
The token of the user associated with the transaction.
-
The amount being funded; this must be the whole amount of the transaction if
partial_approval_capableisfalse.
The following is a sample JIT Funding response.
For the purposes of this scenario, continue to the next step.
Note
In some cases, the JIT Funding request includes address verification data. This data compares the address provided by the cardholder with address data held on file by the Marqeta platform. You can use this data to help make your funding decision. If the included address data is incorrect or out of date, you can override it in your JIT Funding response.For more information, see Using AVS with JIT Funding.
Step 9 — Review the transaction
Copy section link
After your gateway responds to a JIT Funding request, the Marqeta platform sends a JIT Funding notification to your endpoint—your mock endpoint should have received this notification in Step 7. In a production environment, your system would use this data to update your ledger and ensure that the transaction concluded appropriately.
A JIT Funding notification contains two transaction messages:
-
The authorization transaction event – A record of the merchant’s authorization request, noted by the type "authorization".
-
The JIT Funding transaction event – A record of the user’s account being funded, noted by the type "gpa.credit.authorization".
For more information on transaction types, see Event Types.
For this scenario, review the notification to ensure that the Marqeta platform properly handled your JIT Funding response. An approved transaction notification with funding approved by your gateway looks like the following: