Marqeta.com
Support
/
5 minute read
December 4, 2020

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

Concepts

Address Verification System

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

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

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.

Note
You should only include the
address_verification.gateway
object if you intend to override the AVS match determination made by the Marqeta platform.

Tutorial

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 click "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 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 page.

Step 2 — Create your resources

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 at least 20 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.)

Copied

Is this helpful?

Yes
No

Submit a

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

Copied

Is this helpful?

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

Copied

Is this helpful?

Yes
No

Submit a

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

Copied

Is this helpful?

Yes
No
Step 3 — Simulate a transaction

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.

Copied

Is this helpful?

Yes
No
Note
For more information on the
/simulate
endpoint, see Simulating Transactions.
Step 4 — Receive the JIT Funding request on your gateway

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:

Copied

Is this helpful?

Yes
No

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

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.

Copied

Is this helpful?

Yes
No
Step 6 — Review the transaction

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

An approved transaction notification containing AVS data overridden by your gateway looks like the following:

Copied

Is this helpful?

Yes
No
Note
You can also send a
GET
request to the
/transactions
endpoint to review the result of your override.

Feedback on this page?

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