/
10 minute read
September 12, 2023

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 public and private sandbox environments allow 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

Concepts

JIT Funding

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

A program gateway funding source represents a bank account from which funds are drawn for JIT-funded transactions. In the public and private sandbox environments, 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 /fundingsources/programgateway endpoint, see Program Gateway Funding Sources.

Card product configuration

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 public and private sandbox environments. To create a new card product for production, contact your Marqeta representative for more information.

For a complete description of the /cardproducts endpoint, see Card Products.

Your gateway endpoint

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

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 200 OK HTTP response code. If your system does not respond with the 200 OK HTTP response code, the Marqeta platform will try to resend the message. For more information about the Marqeta platform webhook system, see About Webhooks.

Tutorial

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 select Submit Request.

Step 1 — Set up a mock endpoint

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

To define the bank account from which funds are drawn for transactions, create a program gateway funding source.

Send a POST request to the /fundingsources/programgateway endpoint to create a new program gateway funding source.

Populate the basic_auth_username and basic_auth_password fields with values of your choice. The basic_auth_password must contain 20 to 50 characters, with at least one uppercase letter, one lowercase letter, one number, and one symbol. In a production environment, you would use the credentials for your environment. (Neither the username or password will be reused later in the tutorial.)

JSON
Copied

Is this helpful?

Yes
No

Step 3 — Create a card product

To define attributes and behaviors for a set of cards, create a card product. The program_gateway_funding_source object defines the funding source associated with the card product.

Send a POST request to the /cardproducts endpoint to create a new card product. Use the program gateway funding source you created in this tutorial.

JSON
Copied

Is this helpful?

Yes
No

Step 4 — Create a user

Before you create a new card, you must create a user who will own the card.

Send a POST request to the /users endpoint to create a new user.

JSON
Copied

Is this helpful?

Yes
No

Step 5 — Create a card

Send a POST request to the /cards endpoint to create a new card. Use the card product and user tokens you created in this tutorial.

JSON
Copied

Is this helpful?

Yes
No

Step 6 — Simulate a transaction

Now that you have created a card, you can use it to simulate a transaction.

Send the following POST request to /simulate/authorization to simulate a transaction. Use the card token and mock endpoint you created in this tutorial.

JSON
Copied

Is this helpful?

Yes
No
Note
For more information on the /simulate endpoint, see Simulating Transactions.

Step 7 — Receive the JIT Funding request on your gateway

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.

JSON
Copied

Is this helpful?

Yes
No

Step 8 — Return a JIT Funding response

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 OK or 402 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_capable is false.

The following is a sample JIT Funding response.

JSON
Copied

Is this helpful?

Yes
No

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

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:

JSON
Copied

Is this helpful?

Yes
No
Note
You can also send a GET request to the /transactions endpoint to review the result of your funding response. See all transaction response fields in Transactions.

Gateway JIT Funding implementation sample code

Marqeta offers Java sample code to demonstrate how to implement Gateway Just-in-Time (JIT) Funding. You can also use the sample code to learn about how real-world transactions work, even if you do not plan to implement JIT Funding in your program.

The sample code creates a user, card product, card, webhook endpoint, and JIT gateway endpoint for you to use in your public or private sandbox environment. The sample code uses these resources to simulate several common transaction scenarios so that you can view their results and better understand how each component works during a JIT Funding transaction.

The sample code uses Simulations 2.0 to simulate several common transaction scenarios such as authorization and clearing, PIN debit transactions, and various error-handling scenarios, including:

  • Basic authorization and clearing

  • Authorization and clearing with multiple clearings for a single authorization

  • Authorization and clearing with clearing amount greater than authorization amount

  • Authorization, followed by advice and clearing

  • Initial authorization, followed by incremental authorization and clearing

  • Clearing only (i.e., force post)

  • Basic PIN debit scenario

  • Various error-handling scenarios

The preceding list is not exhaustive, because new scenarios are added to the sample code regularly.

If you are interested in using the JIT Funding implementation sample code, contact your Marqeta representative for more information. If you do not yet have a Marqeta representative, contact us here.

Subscribe to our developer newsletter