DOCS

New!

Support
Sign in to get developer support

Marqeta Home

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

5 minute read

October 2, 2019

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

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 card holder’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.

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
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 click "Submit Request".

Step One: 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 page.

Step Two: 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 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.)

{
  "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

Submit a POST 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

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.

{
  "token": "**YOUR USER TOKEN**",
  "address1": "2000 High St",
  "postal_code": "94601"
}

Is this helpful?
Develop Now!

Sign in and use your sandbox to access the API Explorer

Submit a POST 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 Three: 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.

{
  "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",
    "postal_code": "94702",
    "country_code": "USA"
  },
  "card_options":{
    "billing_address":{
      "address": "2000 High St",
      "postal_code": "94601"
    }
  },
  "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 Four: 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:

{
  "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,
      "address_verification" : {
        "request" : {
          "street_address" : "2000 High St",  // Purchaser street address, provided by merchant
          "postal_code" : "94601" // Purchaser postal code, provided by merchant
        },
        "issuer" : {
          "on_file" : {
            "street_address" : "123 Oak St", // Cardholder street address, held by the Marqeta platform
            "postal_code" : "94601" // Cardholder postal code, held by the Marqeta platform
          },
          "response" : {
            "code" : "0100", // Match determination, per the Marqeta platform
            "memo" : "Address mismatch; postal code match" // Memo describing the match determination
          }
        }
      }
    },
    ...
  },
  ...
}

Is this helpful?

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

{
  "jit_funding": {
    "token": "**YOUR JIT FUNDING REQUEST TOKEN**",
    "method": "pgfs.authorization",
    "user_token": "**YOUR USER TOKEN**",
    "amount": "10.00",
    "address_verification": {
      "gateway": {
        "on_file": {
          "street_address": "2000 High St", // The street address held by your system.
          "postal_code": "94601" // The postal code held by your system.
        },
        "response": {
          "code": "0000", // The match determination response code provided by your system.
          "memo": "Address and postal code match" // The memo describing the match determination.
        }
      }
    },
    "original_jit_funding_token": "**YOUR JIT FUNDING REQUEST TOKEN**"
  }
}

Is this helpful?

Step Six: 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 page.

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

{
  "transactions": [
    {
     "type": "authorization",
     "state": "PENDING",
     "token": "ac93792f-f3b4-42e7-a4d8-2c2c62864905",
     "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": "352b6040-2044-48d5-93d9-230306e27021",
         "amount": 10,
         "created_time": "2018-07-31T21:05:19Z",
         "last_modified_time": "2018-07-31T21:05:19Z",
         "transaction_token": "0d8f6d55-c55c-4b97-84c8-94b83645292d",
         "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-07-31T20:55:10Z",
                 "last_modified_time": "2018-07-31T20:55:10Z"
             },
             "gateway_log": {
                 "order_number": "ac93792f-f3b4-42e7-a4d8-2c2c62864905",
                 "transaction_id": "9bf7a707-1985-450b-a2a2-0cb9c62aef93",
                 "message": "Approved or completed successfully",
                 "duration": 135,
                 "timed_out": false,
                 "response": {
                     "code": "200",
                     "data": {
                         "jit_funding": {
                             "token": "9bf7a707-1985-450b-a2a2-0cb9c62aef93",
                             "method": "pgfs.authorization",
                             "user_token": "jit_User_001",
                             "amount": 10,
                             "original_jit_funding_token": "9bf7a707-1985-450b-a2a2-0cb9c62aef93",
                             "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": "fd5fbbbd-9c7e-41d2-ba0b-bdb8bf1b7dae",
             "method": "pgfs.authorization",
             "user_token": "494aea0d-c476-4f86-b831-8d28ccfa3d8f",
             "acting_user_token": "494aea0d-c476-4f86-b831-8d28ccfa3d8f",
             "amount": 10,
             "address_verification": {
                 "request": {
                     "street_address": "2000 High St",
                     "postal_code": "94601"
                 },
                 "issuer": {
                     "on_file": {
                         "street_address": "123 Oak St",
                         "postal_code": "94601"
                     },
                     "response": {
                         "code": "0100",
                         "memo": "Address mismatch; postal code match"
                     }
                 }
             }
         },
         "user_token": "494aea0d-c476-4f86-b831-8d28ccfa3d8f",
         "currency_code": "USD"
     },
     "duration": 485,
     "created_time": "2018-07-31T21:05:18Z",
     "user_transaction_time": "2018-07-31T21:05:18Z",
     "settlement_date": "2018-07-31T00:00:00Z",
     "request_amount": 10,
     "amount": 10,
     "issuer_interchange_amount": 0,
     "currency_code": "USD",
     "approval_code": "968150",
     "response": {
         "code": "0000",
         "memo": "Approved or completed successfully"
     },
     "network": "VISA",
     "subnetwork": "VISANET",
     "acquirer_fee_amount": 0,
     "acquirer": {
         "system_trace_audit_number": "219997"
     },
     "user": {
         "metadata": {}
     },
     "card": {
         "metadata": {}
     },
     "address_verification": {
         "request": {
             "street_address": "2000 High St",
             "postal_code": "94601"
         },
         "on_file": {
             "street_address": "2000 High St",
             "postal_code": "94601"
         },
         "response": {
             "code": "0000",
             "memo": "Address and postal code match"
         }
     },
     "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
     }
   },
   {
     "type": "gpa.credit.authorization",
     "state": "PENDING",
     "token": "0d8f6d55-c55c-4b97-84c8-94b83645292d",
     "user_token": "jit_User_001",
     "acting_user_token": "jit_User_001",
     "card_token": "jit_card_005",
     "preceding_related_transaction_token": "ac93792f-f3b4-42e7-a4d8-2c2c62864905",
     "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": "352b6040-2044-48d5-93d9-230306e27021",
         "amount": 10,
         "created_time": "2018-07-31T21:05:19Z",
         "last_modified_time": "2018-07-31T21:05:19Z",
         "transaction_token": "0d8f6d55-c55c-4b97-84c8-94b83645292d",
         "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-07-31T20:55:10Z",
                 "last_modified_time": "2018-07-31T20:55:10Z"
             },
             "gateway_log": {
                 "order_number": "ac93792f-f3b4-42e7-a4d8-2c2c62864905",
                 "transaction_id": "9bf7a707-1985-450b-a2a2-0cb9c62aef93",
                 "message": "Approved or completed successfully",
                 "duration": 135,
                 "timed_out": false,
                 "response": {
                     "code": "200",
                     "data": {
                         "jit_funding": {
                             "token": "9bf7a707-1985-450b-a2a2-0cb9c62aef93",
                             "method": "pgfs.authorization",
                             "user_token": "jit_User_001",
                             "amount": 10,
                             "original_jit_funding_token": "**YOUR JIT FUNDING REQUEST 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": "fd5fbbbd-9c7e-41d2-ba0b-bdb8bf1b7dae",
             "method": "pgfs.authorization",
             "user_token": "jit_User_001",
             "acting_user_token": "jit_User_001",
             "amount": 10,
             "address_verification": {
                 "request": {
                     "street_address": "2000 High St",
                     "postal_code": "94601"
                 },
                 "issuer": {
                     "on_file": {
                         "street_address": "123 Oak St",
                         "postal_code": "94601"
                     },
                     "response": {
                         "code": "0100",
                         "memo": "Address mismatch; postal code match"
                     }
                 }
             }
         },
         "user_token": "jit_User_001",
         "currency_code": "USD"
     },
     "duration": 274,
     "created_time": "2018-07-31T21:05:19Z",
     "user_transaction_time": "2018-07-31T21:05:19Z",
     "amount": 10,
     "currency_code": "USD",
     "response": {
         "code": "0000",
         "memo": "Approved or completed successfully"
     },
     "network": "MARQETA",
     "subnetwork": "GATEWAY_JIT",
     "acquirer": {
         "system_trace_audit_number": "219997"
     },
     "user": {
         "metadata": {}
     },
     "card": {
         "metadata": {}
     },
     "address_verification": {
         "request": {
             "street_address": "2000 High St",
             "postal_code": "94601"
         },
         "on_file": {
             "street_address": "2000 High St",
             "postal_code": "94601"
         },
         "response": {
             "code": "0000",
             "memo": "Address and postal code match"
         }
     },
     "pos": {
         "partial_approval_capable": true,
         "purchase_amount_only": false,
         "is_recurring": false
     }
    }
  ]
}

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

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.