Using AVS with JIT Funding
When returning a response to a Gateway Just-in-Time (JIT) Funding request, you can override the address data and match determination provided by the Address Verification System (AVS). To override the Marqeta platform’s AVS data, you must include a new address and match determination in your JIT Funding response.
Note
This functionality is only available if your program is configured for Gateway JIT Funding. If you are preloading funds or using Managed JIT Funding, which do not rely on interacting with your system, you cannot override the Marqeta platform’s AVS data.At the end of this guide, you should understand:
-
The role of AVS in JIT Funding requests.
-
How to override the AVS address data and match determination using your gateway endpoint’s JIT Funding response.
Prerequisites
Copy section link
-
Read the Core API Quick Start.
Concepts
Copy section link
Address Verification System
Copy section link
AVS validates the identity of purchasers by comparing the address data they provide against the cardholder’s data held on file. The Marqeta platform makes a match determination describing whether or not the two street addresses or postal codes match. Depending on your card product’s configuration, a failed address match can result in a declined transaction.
For more information on AVS, see About Address Verification.
Just-in-Time Funding
Copy section link
JIT Funding enables you to load funds into user accounts at transaction time.
If you use Gateway JIT Funding, your system’s gateway endpoint receives requests for funding, which your system approves or denies.
JIT Funding requests include AVS data in the jit_funding.address_verification
object.
For more information about JIT Funding, see About Just-in-Time Funding.
The address_verification object
Copy section link
Th address_verification
object contains address data provided by the purchaser, address data held by Marqeta, and the Marqeta platform’s match determination.
If your system’s address data is more up to date than what is provided by the Marqeta platform, you can override the AVS match determination by including the address_verification.gateway
object in your JIT Funding response.
You must include the address data you hold on your system and an updated response code.
Your funding decision (whether to approve or deny funding for a transaction) is independent of your AVS override.
Tip
You should only include theaddress_verification.gateway
object if you intend to override the AVS match determination made by the Marqeta platform.
Tutorial
Copy section link
The following tutorial walks you through overriding the Marqeta platform’s AVS address data and match determination. In this scenario, you will simulate a transaction, review the JIT Funding request, and see what a JIT Funding response that overrides the Marqeta platform’s AVS data looks like.
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
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 for receiving notifications. This tutorial, however, does not require you to set up a gateway 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 the Gateway JIT Funding Messages API reference page.
Step 2 — Create your resources
Copy section link
Create the following resources on the Marqeta platform.
Submit a POST
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.)
Submit a POST
to the /cardproducts
endpoint to create a new card product.
Use the program gateway funding source you created in this tutorial.
Note
You cannot create a program gateway funding source or card product in a production environment. Contact your Marqeta representative to manage these resources.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.
Submit a POST
to the /cards
endpoint to create a new card.
Use the card product and user tokens you created in this tutorial.
Step 3 — Simulate a transaction
Copy section link
Submit the following POST
request to /simulate/authorization
to simulate a transaction.
Use the card token and mock endpoint you created in this tutorial.
Include the card_options
object to simulate the merchant’s on-file address.
For more information on the /simulate
endpoint, see Simulating Transactions.
Step 4 — 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 a 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 showing the relevant AVS data:
Note the four-digit "0100" code in the response. The Marqeta platform determined that the purchaser’s address and the on-file address on the Marqeta platform do not match.
Step 5 — Override the AVS data in your JIT Funding response
Copy section link
For this scenario, we will assume that your system has a more recent address for the purchaser that matches the address returned by the Marqeta platform, and you want your gateway to approve the transaction.
In a production environment, your gateway endpoint programmatically returns the following JIT Funding response.
The address_verification.gateway
object contains the updated address data.
You should only include this object in your JIT Funding response if you intend to override the AVS data.
Step 6 — 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. In a production environment, your system would use this data to ensure that the transaction concluded appropriately.
A JIT Funding notification contains two transaction messages: the authorization message (a record of the merchant’s authorization request, noted by the type "authorization") and the JIT Funding message (a record of the user’s account being funded, noted by the type "gpa.credit.authorization"). For more information on transaction types, see the Event Types API reference page.
An approved transaction notification containing AVS data overridden by your gateway looks like the following:
Tip
You can also send aGET
request to the /transactions
endpoint to review the result of your override.