Using AVS with JIT Funding

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.

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.

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.

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.

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.

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.

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.

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.

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.

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: