Configuring Managed JIT Funding

You can programmatically fund accounts at transaction time by configuring your cards to use Managed Just-in-Time (JIT) Funding. A card configured for Managed JIT Funding requires a card product associated with a program funding source.

Note: The shared sandbox environment allows you to create and configure the resources required for a Managed JIT Funding setup. To implement these configurations in a production environment, contact your Marqeta Customer Success representative.

At the end of this guide, you should understand:

  • The role of the program funding source in Managed JIT Funding.
  • 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 Managed JIT Funding setup, the Marqeta platform handles all authorization decisions using spend controls. Funds are drawn from the program funding source of the card product.

For more information about JIT Funding, see About Just-in-Time Funding.

The program funding source

A program funding source represents a bank account from which funds are drawn for JIT-funded transactions. In the shared sandbox, each program funding source simulates funds for your test transactions. In a production environment, each program funding source draws from the bank account you specify.

Note: Your program funding source must be approved by Marqeta and the issuing bank. 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 Customer Success representative for more information.

For a complete description of the /fundingsources endpoint, see Funding Sources.

Card product configuration

A card product defines the attributes and behaviors of a set of cards. Managed JIT Funding setups require you to create a card product associated with a program funding source. Each card product can have a single funding source, which funds all transactions conducted using an associated card.

Note: You can create and configure card products in the shared sandbox. To create a new card product in production, contact your Marqeta Customer Success representative for more information.

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


Tutorial

The following tutorial walks you through creating and testing the resources required for a Managed JIT Funding setup. In this scenario, you will create a card configured for Managed JIT Funding, use it to 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 One: Create a program funding source

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

Submit a POST to the /fundingsources/program endpoint to create a new program funding source.

{
"token": "**YOUR FUNDING SOURCE TOKEN**",
"name": "**YOUR FUNDING SOURCE NAME**"
}

Step Two: Create a card product

To define attributes and behaviors for a set of cards, create a card product. The program_funding_source object defines the funding source used by the card product. In this scenario, you'll use the program funding source you created in Step One.

Submit a POST to the /cardproducts endpoint to create a new card product.

{
"start_date": "2018-05-01",
"token":"**YOUR CARD PRODUCT TOKEN**",
"name": "Example Card Product",
"config": {
"card_life_cycle": {
"activate_upon_issue": true
},
"jit_funding": {
"program_funding_source": {
"funding_source_token": "**YOUR FUNDING SOURCE TOKEN**",
"refunds_destination": "PROGRAM_FUNDING_SOURCE",
"enabled": true
}
}
}
}

Step Three: Create a user

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

Submit a POST to the /users endpoint to create a new user.

{
"token": "**YOUR USER TOKEN**"
}

Step Four: Create a card

To enable the user to spend funds, create a card. Use the card product and user tokens you created in this tutorial.

Submit a POST to the /cards endpoint to create a new card.

{
"token":"**YOUR CARD TOKEN**",
"user_token":"**YOUR USER TOKEN**",
"card_product_token":"**YOUR CARD PRODUCT TOKEN**"
}

Step Five: Simulate a transaction

Now that you have created a card, you can use it to simulate a transaction. Use the card token you created in this tutorial.

Submit a POST to the /simulate/authorization endpoint to simulate a transaction.

In the webhook.endpoint field, include a URL that points to a webhook endpoint on your system or another mock endpoint you create. (You can use a mock endpoint service like beeceptor.com to receive webhook notifications from the shared sandbox.)

{
"amount": "10.00",
"mid": "11111",
"card_token": "**YOUR CARD TOKEN**",
"card_acceptor": {
"name": "Chicken Tooth Music",
"street_address": "111 Main St",
"city": "Berkeley",
"state": "CA",
"zip": "94702",
"country_code": "USA"
},
"webhook": {
"endpoint": "**YOUR ENDPOINT URL**",
"username": "my_username",
"password": "My_passw0rd"
}
}

Step Six: Review the transaction

After you simulate the transaction, your webhook endpoint should receive a notification message containing the details of the transaction, including the Marqeta platform's funding decision.

The following is a sample transaction notification based on the transaction you simulated in the previous step. Note that it includes a gpa_order object, which indicates that this transaction used JIT Funding. The gpa_order.funding.source.type field is "program", meaning that this transaction used Managed JIT Funding.

The transaction also contains the tokens of the user, card, and funding source you created.

{
    "type": "authorization",
    "state": "PENDING",
    "token": "24798",
    "user_token": "**YOUR USER TOKEN**",
    "acting_user_token": "**YOUR USER TOKEN**",
    "card_token": "**YOUR CARD TOKEN**",
    "gpa": {
        "currency_code": "USD",
        "ledger_balance": 10,
        "available_balance": 0,
        "credit_balance": 0,
        "pending_credits": 0,
        "impacted_amount": -10,
        "balances": {
            "USD": {
                "currency_code": "USD",
                "ledger_balance": 10,
                "available_balance": 0,
                "credit_balance": 0,
                "pending_credits": 0,
                "impacted_amount": -10
            }
        }
    },
    "gpa_order": {
        "token": "9ea36f5b-0485-423f-9f1b-291034e01358",
        "amount": 10,
        "created_time": "2018-08-01T00:04:34Z",
        "last_modified_time": "2018-08-01T00:04:34Z",
        "transaction_token": "24799",
        "state": "PENDING",
        "response": {
            "code": "0000",
            "memo": "Approved or completed successfully"
        },
        "funding": {
            "amount": 10,
            "source": {
                "type": "program",
                "token": "**YOUR FUNDING SOURCE TOKEN**",
                "active": true,
                "name": "**YOUR FUNDING SOURCE NAME**",
                "is_default_account": false,
                "created_time": "2018-08-01T00:01:56Z",
                "last_modified_time": "2018-08-01T00:01:56Z"
            }
        },
        "funding_source_token": "**YOUR FUNDING SOURCE TOKEN**",
        "user_token": "**YOUR USER TOKEN**",
        "currency_code": "USD"
    },
    "duration": 237,
    "created_time": "2018-08-01T00:04:34Z",
    "user_transaction_time": "2018-08-01T00:04:34Z",
    "settlement_date": "2018-08-01T00:00:00Z",
    "request_amount": 10,
    "amount": 10,
    "issuer_interchange_amount": 0,
    "currency_code": "USD",
    "approval_code": "631494",
    "response": {
        "code": "0000",
        "memo": "Approved or completed successfully"
    },
    "network": "VISA",
    "subnetwork": "VISANET",
    "acquirer_fee_amount": 0,
    "acquirer": {
        "system_trace_audit_number": "847200"
    },
    "user": {
        "metadata": {}
    },
    "card": {
        "metadata": {}
    },
    "card_acceptor": {
        "mid": "11111",
        "mcc": "6411",
        "name": "Chicken Tooth Music",
        "street_address": "111 Main St",
        "city": "Berkeley",
        "state": "CA",
        "postal_code": "94702",
        "country_code": "USA"
    },
    "pos": {
        "partial_approval_capable": true,
        "purchase_amount_only": false,
        "is_recurring": false
    }
}