DOCS
Support

Marqeta Home

/
Developer Guides
Core API Reference
DiVA API Reference
Core API Explorer

10 minute read

September 4, 2020

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

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 /fundingsources/programgateway endpoint, see Program Gateway Funding Sources.

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.

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

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 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
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 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.)

{
  "token": "**YOUR FUNDING SOURCE TOKEN**",
  "basic_auth_username": "my_username",
  "basic_auth_password": "My_20-character-min_password",
  "url": "**YOUR ENDPOINT URL**",
  "name": "**YOUR FUNDING SOURCE NAME**"
}

Is this helpful?
Develop Now!

Sign in and use your sandbox to access the API Explorer

Step 3 — Create a card product
Copy section link

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.

{
  "start_date": "2017-01-01",
  "token":"**YOUR CARD PRODUCT TOKEN**",
  "name": "Example Card Product",
  "config": {
    "fulfillment": {
      "payment_instrument":"VIRTUAL_PAN"
    },
    "poi": {
      "ecommerce": true
    },
    "card_life_cycle": {
      "activate_upon_issue": true
    },
    "jit_funding": {
      "programgateway_funding_source": {
        "funding_source_token": "**YOUR FUNDING SOURCE TOKEN**",
        "refunds_destination": "GATEWAY",
        "enabled": true
      }
    }
  }
}

Is this helpful?
Develop Now!

Sign in and use your sandbox to access the API Explorer

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 POST request to the /users endpoint to create a new user.

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

Is this helpful?
Develop Now!

Sign in and use your sandbox to access the API Explorer

Step 5 — Create a card
Copy section link

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.

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

Is this helpful?
Develop Now!

Sign in and use your sandbox to access the API Explorer

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 POST request to /simulate/authorization to simulate a transaction. Use the card token and mock endpoint you created in this tutorial.

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

Is this helpful?
Develop Now!

Sign in and use your sandbox to access the API Explorer

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

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.

{
  "type" : "authorization",
  "state" : "PENDING",
  "token" : "**YOUR TRANSACTION TOKEN**",
  ...
  "gpa_order" : {
    ...
    "jit_funding" : {
      "token" : "**YOUR JIT FUNDING REQUEST TOKEN**",
      "method" : "pgfs.authorization",
      "user_token" : "**YOUR USER TOKEN**",
      "acting_user_token" : "**YOUR USER TOKEN**",
      "amount" : 10.00
      }
    },
    ...
  },
  ...
}

Is this helpful?

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 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.

{
  "jit_funding": {
    "token": "**YOUR JIT FUNDING REQUEST TOKEN**",
    "method": "pgfs.authorization",
    "user_token": "**YOUR USER TOKEN**",
    "amount": "10.00",
    "original_jit_funding_token": "**YOUR JIT FUNDING REQUEST TOKEN**"
  }
}

Is this helpful?

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:

{
  "transactions": [
    {
     "type": "authorization",
     "state": "PENDING",
     "token": "24974",
     "user_token": "jit_User_001",
     "acting_user_token": "jit_User_001",
     "card_token": "jit_card_005",
     "gpa": {
         "currency_code": "USD",
         "ledger_balance": 20,
         "available_balance": 0,
         "credit_balance": 0,
         "pending_credits": 0,
         "impacted_amount": -10,
         "balances": {
             "USD": {
                 "currency_code": "USD",
                 "ledger_balance": 20,
                 "available_balance": 0,
                 "credit_balance": 0,
                 "pending_credits": 0,
                 "impacted_amount": -10
             }
         }
     },
     "gpa_order": {
         "token": "592b8164-a4af-45ee-ab24-13a4bb43e6b2",
         "amount": 10,
         "created_time": "2018-08-21T17:26:30Z",
         "last_modified_time": "2018-08-21T17:26:30Z",
         "transaction_token": "24975",
         "state": "PENDING",
         "response": {
             "code": "0000",
             "memo": "Approved or completed successfully"
         },
         "funding": {
             "amount": 10,
             "source": {
                 "type": "programgateway",
                 "token": "**********_001",
                 "active": true,
                 "name": "jit_pgfs_001",
                 "is_default_account": false,
                 "created_time": "2018-08-21T17:25:43Z",
                 "last_modified_time": "2018-08-21T17:25:43Z"
             },
             "gateway_log": {
                 "order_number": "24974",
                 "transaction_id": "**YOUR JIT FUNDING TOKEN**",
                 "message": "Approved or completed successfully",
                 "duration": 481,
                 "timed_out": false,
                 "response": {
                     "code": "200",
                     "data": {
                         "jit_funding": {
                             "token": "**YOUR JIT FUNDING TOKEN**",
                             "method": "pgfs.authorization",
                             "user_token": "jit_User_001",
                             "amount": 10,
                             "original_jit_funding_token": "**YOUR JIT FUNDING TOKEN**",
                             "address_verification": {
                                 "gateway": {
                                     "on_file": {
                                         "street_address": "2000 High St",
                                         "postal_code": "94601"
                                     },
                                     "response": {
                                         "code": "0000",
                                         "memo": "Address and postal code match"
                                     }
                                 }
                             }
                         }
                     }
                 }
             }
         },
         "funding_source_token": "**********_001",
         "jit_funding": {
             "token": "251bdc52-588a-4291-8c5d-6ded3a67e1a8",
             "method": "pgfs.authorization",
             "user_token": "jit_User_001",
             "acting_user_token": "jit_User_001",
             "amount": 10
         },
         "user_token": "jit_User_001",
         "currency_code": "USD"
     },
     "duration": 622,
     "created_time": "2018-08-21T17:26:29Z",
     "user_transaction_time": "2018-08-21T17:26:29Z",
     "settlement_date": "2018-08-21T00:00:00Z",
     "request_amount": 10,
     "amount": 10,
     "issuer_interchange_amount": 0,
     "currency_code": "USD",
     "approval_code": "761515",
     "response": {
         "code": "0000",
         "memo": "Approved or completed successfully"
     },
     "network": "VISA",
     "subnetwork": "VISANET",
     "acquirer_fee_amount": 0,
     "acquirer": {
         "institution_country": "840",
         "institution_id_code": "428399181",
         "retrieval_reference_number": "528294182583",
         "system_trace_audit_number": "656761"
     },
     "user": {
         "metadata": {}
     },
     "card": {
         "metadata": {}
     },
     "card_security_code_verification": {
         "type": "CVV1",
         "response": {
             "code": "0000",
             "memo": "Card security code match"
         }
     },
     "fraud": {
         "network": {
             "transaction_risk_score": 97,
             "account_risk_score": 7
         }
     },
     "card_acceptor": {
         "mid": "000000000011111",
         "mcc": "6411",
         "name": "Chicken Tooth Music",
         "address": "111 Main St",
         "city": "Berkeley",
         "country": "USA"
     },
     "pos": {
         "pan_entry_mode": "MAG_STRIPE",
         "pin_entry_mode": "TRUE",
         "terminal_id": "TR100000",
         "terminal_attendance": "ATTENDED",
         "card_holder_presence": false,
         "card_presence": false,
         "partial_approval_capable": false,
         "purchase_amount_only": false,
         "is_recurring": false
     },
     "transaction_metadata": {
         "payment_channel": "OTHER"
     }
 },
 {
     "type": "gpa.credit.authorization",
     "state": "PENDING",
     "token": "24975",
     "user_token": "jit_User_001",
     "acting_user_token": "jit_User_001",
     "card_token": "jit_card_005",
     "preceding_related_transaction_token": "24974",
     "gpa": {
         "currency_code": "USD",
         "ledger_balance": 20,
         "available_balance": 0,
         "credit_balance": 0,
         "pending_credits": 0,
         "impacted_amount": 10,
         "balances": {
             "USD": {
                 "currency_code": "USD",
                 "ledger_balance": 20,
                 "available_balance": 0,
                 "credit_balance": 0,
                 "pending_credits": 0,
                 "impacted_amount": 10
             }
         }
     },
     "gpa_order": {
         "token": "592b8164-a4af-45ee-ab24-13a4bb43e6b2",
         "amount": 10,
         "created_time": "2018-08-21T17:26:30Z",
         "last_modified_time": "2018-08-21T17:26:30Z",
         "transaction_token": "24975",
         "state": "PENDING",
         "response": {
             "code": "0000",
             "memo": "Approved or completed successfully"
         },
         "funding": {
             "amount": 10,
             "source": {
                 "type": "programgateway",
                 "token": "**********_001",
                 "active": true,
                 "name": "jit_pfgs_001",
                 "is_default_account": false,
                 "created_time": "2018-08-21T17:25:43Z",
                 "last_modified_time": "2018-08-21T17:25:43Z"
             },
             "gateway_log": {
                 "order_number": "24974",
                 "transaction_id": "**YOUR JIT FUNDING TOKEN**",
                 "message": "Approved or completed successfully",
                 "duration": 481,
                 "timed_out": false,
                 "response": {
                     "code": "200",
                     "data": {
                         "jit_funding": {
                             "token": "**YOUR JIT FUNDING TOKEN**",
                             "method": "pgfs.authorization",
                             "user_token": "jit_User_001",
                             "amount": 10,
                             "original_jit_funding_token": "**YOUR JIT FUNDING TOKEN**",
                             "address_verification": {
                                 "gateway": {
                                     "on_file": {
                                         "street_address": "2000 High St",
                                         "postal_code": "94601"
                                     },
                                     "response": {
                                         "code": "0000",
                                         "memo": "Address and postal code match"
                                     }
                                 }
                             }
                         }
                     }
                 }
             }
         },
         "funding_source_token": "**********_001",
         "jit_funding": {
             "token": "251bdc52-588a-4291-8c5d-6ded3a67e1a8",
             "method": "pgfs.authorization",
             "user_token": "jit_User_001",
             "acting_user_token": "jit_User_001",
             "amount": 10
         },
         "user_token": "jit_User_001",
         "currency_code": "USD"
     },
     "duration": 537,
     "created_time": "2018-08-21T17:26:29Z",
     "user_transaction_time": "2018-08-21T17:26:29Z",
     "amount": 10,
     "currency_code": "USD",
     "response": {
         "code": "0000",
         "memo": "Approved or completed successfully"
     },
     "network": "MARQETA",
     "subnetwork": "GATEWAY_JIT",
     "acquirer": {
         "institution_country": "840",
         "institution_id_code": "428399181",
         "retrieval_reference_number": "528294182583",
         "system_trace_audit_number": "656761"
     },
     "user": {
         "metadata": {}
     },
     "card": {
         "metadata": {}
     },
     "card_security_code_verification": {
         "type": "CVV1",
         "response": {
             "code": "0000",
             "memo": "Card security code match"
         }
     },
     "fraud": {
         "network": {
             "transaction_risk_score": 97,
             "account_risk_score": 7
         }
     },
     "pos": {
         "pan_entry_mode": "MAG_STRIPE",
         "pin_entry_mode": "TRUE",
         "terminal_attendance": "ATTENDED",
         "card_holder_presence": false,
         "card_presence": false,
         "partial_approval_capable": false,
         "purchase_amount_only": false,
         "is_recurring": false
     },
     "transaction_metadata": {
         "payment_channel": "OTHER"
     }
    }
  ]
 }
}

Is this helpful?
Note
You can also send a GET request to the /transactions endpoint to review the result of your funding response.

Related Materials

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.