Expense Management with Gateway JIT Funding

Hidden

Warning
This page is strictly internal to Marqeta, and is not to be shared outside the organization.

Overview

This Expense Management with Gateway Just-in-Time (JIT) Funding use case guide describes how to design, build, and integrate an expense management use case on the Marqeta platform. Your expense management program will be Managed By Marqeta. Your sandbox and production environments will be configured on your behalf by Marqeta. This guide provides a detailed description of what Marqeta configures for you, as well as a step-by-step guide on how to use our APIs to create users and cards, and make transaction funding decisions. After completing the tasks described in this guide, you will be ready to work with Marqeta’s Integration Engineering team to move your expense management program into production.

Prerequisites

Before you can receive your sandbox environment credentials, you must provide Marqeta with the following information:

The IP addresses of any servers that will connect to the APIs in your sandbox and production environments. Sandbox environment IP addresses are required before you can access your sandbox. Production environment IP addresses can be provided at a later date.
The details of your JIT Funding gateway endpoint in order to send transaction messages for you to approve or decline. You must provide the URL, basic authentication username and password, and name of your JIT Funding gateway endpoint to Marqeta.

Perform these tasks to begin your technical integration with Marqeta:

Familiarize yourself with the developer guides and Core API references.

Set up a public sandbox account and begin experimenting with the Core API Quick Start.

Review this guide with a Marqeta Solutions Engineer.

Provide IP addresses and gateway connection details to Marqeta.

Receive your sandbox environment credentials from Marqeta.

Validate your connection to your sandbox environment.

Set up user and card test data.

Submit test transactions to Marqeta.

Develop, test, and iterate on your Marqeta API integration.

Technical overview

This section provides a technical overview of the Expense Management with Gateway JIT Funding use case.

Components

Your technical integration with the Marqeta platform will typically contain these main components.

Businesses, users, cards, and accounts

Businesses, users, cards, and accounts are the primary resources you work with to configure and maintain your card program. You will integrate with the Marqeta platform to manage the following:

The lifecycle of your business and user account holders through creation, Know Your Business (KYB) or Know Your Customer (KYC) verification, activation, deactivation, and more
The configuration and funding of accounts
The relationships between users, cards, and accounts
The lifecycle of cards through issuing, activation, suspension, and termination

The primary account holders for expense management programs are businesses, and you will use parent-child relationships between businesses and their users to fund card transactions.

JIT Funding gateway

The JIT Funding gateway is the mechanism through which you will make real-time authorization and funding decisions on individual transactions at the time of purchase.

Important
It is essential that this component be highly available and capable of responding within the service-level agreement of 3000 ms for a transaction authorization.

Ledger management

Your system must incorporate a ledger management system to track transactions and their impact on individual account balances. Marqeta sends transaction-level summary data using webhooks. You must establish one to five active endpoints for consuming these webhooks, and incorporate ledger management capabilities as required by your card program.

Design principles for your Marqeta integration

Keep these principles in mind while designing your integration with Marqeta:

Marqeta’s APIs are idempotent.
Use Gateway JIT Funding messages for authorization decisions and webhooks for ledger management.
Your JIT Funding gateway endpoint should be highly available and responsive. Gateway requests taking longer than 3000 ms will time out, potentially leading to unwanted authorization declines.
Manage webhook events in chronological order by the top-level transaction token.
Respond to webhooks as soon as they are received. Marqeta will resend webhooks until a successful HTTP 200 response is acknowledged.

Resources

Use the resources listed below to learn about and integrate with the Marqeta platform.

Integration environments

You will work with the Marqeta platform in three distinct environments: the public sandbox, your private sandbox, and your production environment.

Public sandbox: A multi-tenant shared environment that you can access at any time. The public sandbox is best used for understanding Marqeta APIs and sample requests and responses for various endpoints.
Private sandbox: Configured by Marqeta as a single-tenant environment for the specific use case you will be using in production. Your private sandbox is a staging environment with the functional elements of the production APIs, excluding the live production connection to the card networks and digital wallet providers.
Production environment: Configured by Marqeta as a single-tenant environment for your production launch, according to your specific use case. Your production environment is connected to the card networks and has a working Bank Identification Number (BIN) associated with the issued cards.

API visualizations

You can see visualizations of the expense management API configuration at swimlanes.io.

Gateway JIT Funding implementation sample code

Marqeta offers Java sample code to demonstrate how to implement Gateway Just-in-Time (JIT) Funding. You can also use this sample code to learn the ins-and-outs of real-world card transactions, even if you do not plan to implement JIT Funding in your card program. The sample code creates a user, card product, card, webhook endpoint, and JIT Funding gateway endpoint for you to use in your public or private sandbox environment. It then uses these resources to simulate several common transaction scenarios so that you can view their results and better understand the role of each component as part of a JIT Funding transaction. The sample code uses Simulations 2.0 to simulate several common transaction scenarios, including:

Basic authorization and clearing
Authorization and clearing with multiple clearings for a single authorization
Authorization and clearing with a clearing amount greater than the authorization amount
Authorization, followed by advice and clearing
Initial authorization, followed by incremental authorization and clearing
Clearing only (force post)
Basic PIN debit scenario
Various error-handling scenarios

The preceding list is not exhaustive, because new scenarios are added to the sample code regularly. You can download the JIT Funding implementation sample code from the Marqeta GitHub repository.

Developer documentation

The Guides collection provide information about the Marqeta platform’s many features and capabilities, as well as helpful concepts and tutorials. The Core API Reference provides detailed reference documentation for all of Marqeta’s API endpoints.

Building and testing your card program

This section describes how you—in partnership with Marqeta—will build and test your expense management program. To build your card program, follow these steps:

Create a business and submit it for Business KYC verification.

After your business has passed Business KYC verification, create your users.

Create cards and assign them to your users.

Card products and account holder groups

Marqeta provides you with a private sandbox environment that includes the following resources, depending on your card program’s functional and regulatory requirements:

Component	Description	Program-Specific Considerations
Card products	Card products specify virtual and physical card form factors, as well as the product configurations you offer to your users.	Your expense management program can use virtual and physical cards, as well as digital wallet tokenization.
Account holder groups	Account holder groups represent classes of end users and govern the requirements for KYC or KYB verification.	Business KYC verification is required for your business customers. User KYC verification is not required for your cardholders. Marqeta will create two account holder groups for your card program: `DEFAULT_AHG` and `no_kyc_required`: - DEFAULT_AHG: Business KYC is required for accounts in the `DEFAULT_AHG` group. - no_kyc_required: User KYC is not required for the cardholders in the `no_kyc_required` group. Cardholders are represented by `user` resources on the Marqeta platform. Every time you create a business, assign it to the `DEFAULT_AHG` group. Every time you create a user who is not a beneficial owner of the business, assign it to the `no_kyc_required` group.
Spend controls	Your preconfigured spend controls include program-level controls required by the issuing bank, such as velocity controls, accepted countries, and restricted merchant categories.	Some additional spend controls, such as individual card spend limits and merchant category restrictions, may also apply to your card program.

You are responsible for managing the lifecycle of businesses, users, and cards in your program. The following sections describe how to manage those lifecycles using Marqeta’s APIs, and provide management tips.

Business management

For the expense management use case, your customer is commonly a business, and your card-holding users are authorized users of that business, under a parent-child relationship. You must submit your business customers for Business KYC (KYB) verification prior to creating users or issuing cards.

API Action and Endpoint	Description
`POST /businesses`	Creates a new `business` resource, ensuring that you use the `DEFAULT_AHG` account holder group token created for you by Marqeta. When creating the business, ensure that you include the information required for KYC verification.
`POST /kyc`	Submits the business for KYC verification. The new business must pass KYC verification before any cards can be issued.

About the Business KYC process

Below are tips on the Business KYC process:

Individual KYC is not required for most users who are child accounts of the business. The exception is for any users who are considered beneficial owners of the company.
You can perform KYC twice on any given business, regardless of outcome. Attempting to perform KYC a third time on a given business returns an error.
If all business components pass KYC verification, the KYC status is SUCCESS. Marqeta will send you a businesstransition.active webhook event for confirmation.
If any business component fails KYC verification, the KYC status is FAILURE. Marqeta will send you a businesstransition.suspended webhook event for confirmation.
If any business component has pending KYC verification, the KYC status is PENDING. Marqeta will send you a businesstransition.limited webhook event for confirmation.
If the business component has been successfully submitted for verification, but the outcome was not determined in the allotted time, the KYC status is VENDOR_PENDING. Marqeta will send you the final outcome for your KYC verification request using a kybresults webhook event.
See Business KYC outcome reasons for the KYC outcome reasons returned in the outcome_reasons field of the Business KYC result response object when a business is in a PENDING or FAILURE state. Where possible, it also describes acceptable documents that your customers can submit to resolve PENDING outcomes.
Read the KYB Implementation Guide for information about required KYB testing in your sandbox and production environments.

User management

For the expense management use case, users are most commonly the cardholders to whom cards are assigned. You cannot create users until the business account holder has passed Business KYC verification. To manage your users, you must support these operations:

API Action and Endpoint	Description
`POST /users`	Creates a user. To specify the parent-child relationship between the user and the business, enter a value of `true` in the `uses_parent_account` field, and enter the unique identifier of the business in the `parent_token` field. Users are transitioned to the `ACTIVE` state upon creation.
`GET /users`	Retrieves a list of user resources.
`GET /users/{token}`	Retrieves a specific user resource.
`PUT /users/{token}`	Updates a user resource.
`POST /usertransitions`	Changes the status of a user resource.

Managing card-holding users

Below are tips on managing your card-holding users:

When creating a user, you should specify a unique identifier that is meaningful in your system for the user token. If you choose not to create a user token, the Marqeta platform will create one for you. User tokens cannot be updated after they are created.
If you use digital wallets tokenization or plan to in the future, include the user’s email and phone number in the user resource. Marqeta uses this contact information to send a one-time passcode to verify the user’s identity during the “step-up” verification process.
You can include optional metadata in a user resource in the user.metadata object. User-associated metadata is included in both JIT Funding message payloads and usertransition webhooks.

Below is a sample user object including all mandatory fields and some optional fields:

JSON

{
  "account_holder_group_token": "no_kyc_required",
  "first_name": "Jane",
  "last_name": "Smith",
  "token": "my_user_01",
  "email": "jane@company.com",
  "birth_date": "1991-01-01",
  "address1": "1234 Blake Street",
  "city": "Berkeley",
  "state": "CA",
  "country": "USA",
  "postal_code": "94702",
  "uses_parent_account": "true",
  "parent_token": "my_business_01"
}

Card product and card management

Card products define the capabilities and behaviors of one or more cards. They are represented on the Marqeta platform by the cardproduct resource. Marqeta creates and configures your card product on your behalf. Cards are the individual payment instruments held by users. They are represented on the Marqeta platform by the card resource. To manage your card products and cards, you must support these operations:

API Action and Endpoint	Description
`GET /cardproducts`	Retrieves a list of card products.
`POST /cards`	Creates a card for a user.
`GET /cards/user/{token}`	Retrieves a list of cards for a specific user.
`POST /cardtransitions`	Changes the state of an existing card.

PCI DSS compliance

Certain actions require access to sensitive card data to which the Payment Card Industry Data Security Standard (PCI DSS) applies. All aspects of your card program must adhere to PCI DSS standards. Marqeta offers solutions, regardless of whether your system is PCI DSS compliant or not:

If your system is certified PCI DSS compliant, you can use restricted API endpoints that allow full access to Primary Account Numbers (PANs) and Card Verification Values (CVVs) for all cards. You can also use restricted API endpoints to set personal identification numbers (PINs). You must provide proof of your PCI DSS certification to Marqeta to receive this access.
If your US-based system is PCI DSS non-compliant, Marqeta’s UX Toolkit offers a secure, modern user experience that enables you to self-serve and customize the components to your brand without Marqeta’s help.
If your system is PCI DSS non-compliant and based outside the US, Marqeta provides a JavasScript library called Marqeta.js and customizable widgets that allow you to include necessary functionality in your web or mobile application in a PCI-compliant manner.

Managing cards

Below are tips for managing your physical and virtual cards.

Use the card.metadata object to store transaction-level or program-specific information for reference in reporting or business logic.

Physical cards:

Physical cards are UNACTIVATED upon creation.
When creating a physical card, ensure that you include the personalization object to personalize the card with the user’s name. Also include the shipping object to specify the card shipping address.
Be aware that Marqeta is required to conduct an Office of Foreign Assets Control (OFAC) check on users when the card is personalized with a name.
Marqeta recommends that you receive cardtransition.state webhook events to be notified of changes to the card state and cardtransition.fulfillment webhook events to be notified of changes to the card fulfillment state.
Use the /cardtransitions endpoint to transition the card from the UNACTIVATED state to the ACTIVE state at your discretion.

Virtual cards:

Virtual cards are ACTIVE upon creation.
If your card program is approved to display sensitive card data to the authorized cardholder, use the query parameters show_pan and show_cvv_number to present the virtual card details. After displaying this information to the cardholder, Marqeta transitions the card fulfillment to DIGITALLY_PRESENTED.
If your card program uses Marqeta.js to present the virtual card to the end user, read the Using Marqeta.js guide.

Spend control management

Your preconfigured spend controls include program-level controls required by the issuing bank, such as velocity controls, accepted countries, and restricted merchant categories. Authorization controls limit where a cardholder can spend money. Velocity controls limit how much money they can spend.

Authorization controls

Authorization controls determine where a user is authorized to transact, and for how long an authorization is valid. Controls can be placed at the program, card product, or user level. Authorization controls can be restricted by date and time. Authorization controls allow or deny transactions for merchant category code (MCC) groups, single MCCs, or specific merchant identifiers (MIDs). MID exemptions only allow for one MID per control. MCC Groups determine when an authorization expires. Standard expiry dates are as follows:

By default, authorizations expire after 7 days.
For hotels and car rentals, authorizations expire after 30 days.

A merchant identifier (MID) exemption lets users to transact at a merchant who would otherwise be denied due to an existing authorization control. To manage authorization controls, your card program must support these operations:

API Action and Endpoint	Description
`POST /authcontrols`	Create an authorization control.
`GET /authcontrols`	Retrieve a list of authorization controls.
`GET /authcontrols/{token}`	Retrieve a specific authorization control.
`PUT /authcontrols/{token}`	update an authorization control.
`POST /authcontrols/exemptmids`	Create a merchant identifier exemption.
`PUT /authcontrols/exemptmids{token}`	Update an MID exemption.
`GET /authcontrols/exemptmids`	Retrieve a list of MID exemptions.
`GET /authcontrols/exemptmids{token}`	Retrieve a specific MID exemption.

Velocity controls

Velocity controls limit both the amount a cardholder can spend and the number of transactions they can attempt in a given window of time:

Day
Week
Month
Quarter
Year
Lifetime
Transaction (a single transaction)

Velocity controls also determine which types of transactions a cardholder can perform:

Purchases
Withdrawals
Cashback
Original credit transactions

To manage velocity controls, your card program must support these operations:

API Action and Endpoint	Description
`POST /velocitycontrols`	Create a velocity control.
`GET /velocitycontrols`	Retrieve a list of velocity controls.
`GET /velocitycontrols/{token}`	Retrieve a specific velocity control.
`PUT /velocitycontrols/{token}`	Update a velocity control.
`GET /velocitycontrols/user/{user_token}/available`	Retrieve a list of the available balances of the velocity controls associated with a user.

Gateway JIT Funding implementation

The JIT Funding gateway (also known as the Program Gateway Funding Source or pgfs) is the mechanism through which you will make real-time authorization and funding decisions on individual transactions at the time of purchase. For Gateway JIT Funding enabled programs, actionable JIT Funding messages are sent in real time to your JIT Funding gateway endpoint for authorization. Use transaction data included in the JIT Funding message body to make your funding decision. Authorization or decline of the transaction is determined by the message you send back in response to the authorization request. To understand which JIT Funding messages require your attention, see the jit_funding object topic. A complete JIT Funding response meets the following criteria:

Responds within 3000 ms with either HTTP response code 200 (approval) or HTTP response code 402 (decline).
Includes the token of the incoming request.
Includes the method of the incoming request.
Includes the user_token associated with the request.
Includes the gpa_order.jit_funding.amount being funded.

JSON

{
  "jit_funding": {
    "token": "incoming_request_token",
    "method": "pgfs.authorization",
    "user_token": "my_user_01",
    "amount": "160.17"
  }
}

Transactions that satisfy the constraints imposed by your card program’s authorization and velocity controls are forwarded to the gateway. Any additional logic for authorizing a transaction must be implemented within your JIT Funding gateway endpoint. Use the Simulations API to gain familiarity with the transaction messages that are generated by your card program environment and passed to both your JIT Funding gateway and webhook endpoints. For example, simulate an authorization to send a pgfs.authorization message to your JIT Funding gateway endpoint and an authorization webhook event to your webhook endpoint.

Managing Gateway JIT Funding

Below are tips on managing your Gateway JIT Funding implementation:

Your JIT Funding gateway endpoint must be optimized for high availability and responsiveness. The effectiveness of your card program depends on timely responses to all authorization decisions.
JIT Funding requests contain multiple amount fields. Ensure that you use the value from gpa_order.jit_funding.amount in your decision-making process. This is the amount that you must fund to approve the transaction.

Webhooks and ledger management

Using a Gateway JIT Funding program obligates you to maintain an account ledger system outside of the Marqeta platform. Your account ledger system must adhere to Generally Accepted Accounting Principles (GAAP), undergo periodic reconciliation with other sources, and be duplicated in multiple locations for redundancy. Your system must consume transaction webhooks and update your ledger for each of your users so that you can identify their current, pending, and available balances at any time.

About webhooks

Marqeta sends webhook event notifications for a wide variety of event types. Webhooks are crucial for development of a system of record for ledger management and can be used to automate other interactions as well. You can configure up to five webhook endpoints to receive webhook events using the webhooks API. Your webhook endpoints can be configured to receive all events ( * ), a subset of events of a particular type (transaction.*) or specific events (cardtransition.fulfillment.issued). For more information about webhooks, see About Webhooks. An Integration Engineer will work with you to identify the webhooks to which you should subscribe, depending on your card program’s specific requirements. Your webhook endpoint must respond with HTTP 200 to acknowledge that a webhook has been successfully received. If Marqeta receives no response or a failure response, the webhook delivery will be retried by powers of four after each subsequent messaging failure. The retry interval follows this pattern: 4 seconds, 16 seconds, 64 seconds, and so on, up to an interval just over 12 days. For detailed information about webhook responses and retries, see Runtime characteristics. Webhooks that are not related to card transactions do not apply to ledger management, but they may have important implications for your card program. Review the full list of event types to determine which events are relevant to the business logic of your card program.

Ledger management

Ledger management is an integral part of your Gateway JIT Funding program. It is important to read and understand Marqeta’s best practices for ledger maintenance. The following sections introduce foundational concepts for building your system of record to calculate, manage, and adjust cardholder balances:

Dual-message transaction scenarios

In a dual-message (“signature”) transaction, the merchant submits an electronic message at the time of purchase containing the information required for an authorization decision. At a later point in time, the merchant submits a second message containing additional data required for clearing and settlement. This section describes how to use the Gateway JIT Funding messages and network messages sent to you via webhook to manage your ledger. JIT Funding approvals: When you receive an actionable authorization JIT Funding request message on your gateway endpoint, respond to the Marqeta platform with an HTTP 200 response to approve the authorization. In your ledger, place a temporary hold on the cardholder’s available balance at the time of your JIT Funding response. JIT Funding declines: When you receive an actionable authorization JIT Funding request message on your gateway endpoint, respond to the Marqeta platform with an HTTP 402 response to decline the authorization. If you declined the JIT Funding request, no ledger management is required. You will receive a confirmation of your decline via a transaction.authorization webhook with the status of declined. Webhook authorization approvals: After you have approved the JIT Funding request message, and the transaction has been successfully processed by the Marqeta platform and the card network, the Marqeta platform sends a transaction.authorization webhook with a status of pending. In your ledger, the temporary hold on the cardholder’s available balance should remain unchanged. Webhook authorization declines: Even if you approved the JIT Funding message request, there are still circumstances under which you will receive a transaction.authorization webhook with a status of declined:

Processing error on the Marqeta platform or the card network
Response timeout, if the Marqeta platform did not receive your response within the required three seconds

In these cases, you must remove the temporary hold on the cardholder’s balance, so that their purchasing power is not impacted by the declined transaction. Transaction clearing: Transaction clearing is an asynchronous process in which the Marqeta platform waits to receive batch clearing records from the card network with instructions on the funds needed to clear previously approved transactions. When you receive a transaction.authorization.clearing webhook, you must move the funds from your cardholder’s current balance in your ledger, and remove the temporary hold from the available balance. In dual-message scenarios, especially those with multiple transaction messages, you must associate transaction events with each other to manage and adjust cardholder balances properly.

Use the preceding_related_transaction_token attribute to correlate a subsequent event (such as an authorization.clearing) to its corresponding originating event (such as an authorization).
Use the original_jit_funding_token attribute to correlate associated JIT Funding messages. This field contains the unique identifier of the first associated JIT Funding message. It is not included in the originating JIT Funding messages, but appears in all subsequent related JIT Funding messages.

Single-message transaction scenarios

In a single-message (“PIN debit”) transaction, the merchant submits a single electronic message containing all data required for the authorization, clearing, and settlement of the transaction. JIT Funding approvals: When you receive an actionable pindebit JIT Funding request message on your gateway endpoint, respond to the Marqeta platform with an HTTP 200 response to approve the authorization. In your ledger, place a temporary hold on the cardholder’s available balance at the time of your JIT Funding response. JIT Funding declines: When you receive an actionable pindebit JIT Funding request message on your gateway endpoint, respond to the Marqeta platform with an HTTP 402 response to decline the authorization. If you decline the JIT Funding request, no ledger management is required. You will receive a confirmation of your decline via a transaction.pindebit webhook with the status of declined. Webhook authorization approvals: After you have approved the JIT Funding request message, and the transaction has been successfully processed by the Marqeta platform and the card network, the Marqeta platform sends a transaction.pindebit webhook with a status of completed. When you receive this webhook, you must move the funds from your cardholder’s current balance in your ledger, and remove the temporary hold from the available balance. Webhook authorization declines: Even if you approved the JIT Funding message request, there are still circumstances under which you will receive a transaction.pindebit webhook with a status of declined:

Processing error on the Marqeta platform or the card network
Response timeout, if the Marqeta platform did not receive your response within the required three seconds

In these cases, you must remove the temporary hold on the cardholder’s balance, so that their purchasing power is not impacted by the declined transaction.

Error handling

This section explains how to handle common errors. JIT Funding gateway timeouts: Your JIT Funding gateway must respond to funding requests within three seconds. To troubleshoot JIT Funding gateway timeout issues, check the transaction.authorization or transaction.pindebit webhook messages to ensure that your response was recorded as an approval, rather than as a decline due to a JIT Funding gateway timeout. A value of true in the gateway_log.timed_out field indicates that your JIT Funding response timed out. For more information about handling timeouts, see Managing Timeouts. Marqeta platform and card network timeouts: To troubleshoot Marqeta platform or card network declines, check the transaction.authorization or transaction.pindebit webhook messages for response codes that indicate Marqeta errors or card network errors, such as:

1878: Corresponding JIT load failure.
1842: Account load failed.
1844: The card network has advised of a decline.

For the complete list of transaction response codes, see the response codes section of the About Transactions guide.

Amounts

There are multiple amount fields of which you need to be aware. The JIT Funding request contains multiple amount fields. Ensure that you use the value from gpa_order.jit_funding.amount in your decision-making process, as this is the amount that you must fund in order to approve the transaction. Use the impacted_amount attribute in the webhook to adjust your account ledger as appropriate. This attribute indicates the positive or negative impact on the ledger, based on the transaction type.

Managing an account ledger

Below are tips on managing your account ledger:

Manage your account ledger using webhooks, not JIT Funding messages. Transaction webhook events capture the result of the activity after it has occurred.
Marqeta usually sends webhook events within seconds of the corresponding system event. Ledger updates based on webhook events do not need to be made in real time, but should be “eventually consistent”.
Marqeta resends webhook events at intervals of increasing duration until they are acknowledged with an HTTP 200 response.
Webhooks are not guaranteed to be received in the order in which the triggering events occur. When you need to reconstruct a strict sequence of events, use the webhooks’ created_time attribute along with other contextual information contained in the webhook message body.
Marqeta may deliver webhooks in a batch, with multiple events combined in a single message. Your webhook endpoint must be able to receive and parse multiple events within a single message.
Ensure that your system of record is able to handle exception cases, such as when webhooks are delivered out of the expected order (for instance, when a clearing webhook event is received before the originating authorization webhook event). Such exceptions can occur for a wide variety of reasons outside the control of your system or the Marqeta platform.
When necessary, you can resend webhook event notifications.

Reporting

The Marqeta platform offers three reporting mechanisms:

Webhooks: Event notifications are triggered in real time and delivered to your webhook listener endpoints. You can use webhook events for near-real-time reporting.
Marqeta Dashboard: The Marqeta Dashboard lets you access pre-built and custom reports for a variety of business intelligence and reconciliation needs. Use the Marqeta Dashboard for on-demand and operational reporting.
DiVA API: The Data insights, Visualization, and Analytics (DiVA) API lets you access raw data and preconfigured reports programmatically.

Marqeta Dashboard

The Marqeta Dashboard is available when your card program is in production. It provides a variety of pre-built reports, as well as the ability to create custom reports. Marqeta Dashboard reports support visualizations and can be exported in CSV format. You can build and review reports in the Marqeta Dashboard, then automate them using the DiVA API. For more information about Marqeta Dashboard reports, see Reports in the Dashboard.

DiVA API

The DiVA API is available when your card program is in production, and lets you execute programmatic queries for program information. DiVA requests can be made for on-demand data retrieval, automated report generation, and for populating data warehouses. DiVA data is refreshed three times per day (morning, afternoon, overnight). For more information about the DiVA API, see Exploring the DiVA API.

Settlement and reconciliation

As your issuer processor, Marqeta receives settlement files from the card network (e.g., Visa) and coordinates settlement with the issuing bank partner. Marqeta performs reconciliation to ensure that the Marqeta transaction ledger aligns with card network and bank records. You can retrieve data from Marqeta for ledger reconciliation using the Marqeta Dashboard, webhooks, or the Transactions API.

Important
You must perform your own reconciliation to ensure that your records match Marqeta’s transaction ledger.

Tokenization

Marqeta offers digital wallet tokenization as a managed service for Apple Pay, Google Wallet, and Samsung Wallet for both Visa and Mastercard. To manage your digital wallet token provisioning workflows, you must support these operations:

API Action and Endpoint	Description
`POST /digitalwalletprovisionrequests/applepay`	Returns card data for use in provisioning a token to Apple Pay.
`POST /digitalwalletprovisionrequests/androidpay`	Returns card data for use in provisioning a digital wallet token into Google Wallet.
`POST /digitalwalletprovisionrequests/samsungpay`	Returns card data for use in provisioning a digital wallet token into Samsung Wallet.
`POST /digitalwallettokentransitions`	Transitions a digital wallet token from one state to another.

Provisioning methods

The following methods of digital wallet provisioning are supported:

Manual provisioning: The cardholder enters card details directly into the wallet. Manual provisioning is the only method available for Samsung Wallet.
Card-on-file provisioning: The cardholder provisions an existing card that is already on file.
In-app provisioning (instant issuance): The cardholder provisions a card directly from the mobile application.
Web push provisioning: The cardholder provisions a card directly from a web browser. Available for Apple Wallet and Google Wallet.

For more information about provisioning digital wallet tokens, see Provisioning Digital Wallet Tokens.

Digital wallet token lifecycle

A digital wallet token’s lifecycle is similar to that of a card, but digital wallet tokens and cards each have distinctly separate workflows:

Once terminated, a token cannot be reactivated.
Suspended tokens can be moved back to active.
The digital wallet token state is separate from the card state, and digital wallet tokens continue to work even if a card is not active.
By default, the state of a card only affects the provisioning of new digital wallet tokens.

For more information about the digital wallet token lifecycle, see Managing the Digital Wallet Token Lifecycle.

Digital wallet token provisioning approval flows

Before you can insert a card into a digital wallet, the card network must provision a token to replace the card’s sensitive data. During token provisioning, the digital wallet, the card network, and the Marqeta platform (the issuer processor) each perform identification and verification steps to individually assess the legitimacy of the token provisioning request. Each participant scores the request by tagging it with one of the following colors:

Color	Status	Outcome
Green `DECISION_GREEN`	Provision	If all participants designate `DECISION_GREEN`, the token is immediately provisioned.
Yellow `DECISION_YELLOW`	Further verification	If any participant designates `DECISION_YELLOW` and none designates `DECISION_RED`, the token is placed in a pending state and further “step-up” verification is required. `DECISION_YELLOW` indicates that the participant is unsure of the risk associated with provisioning the token.
Red `DECISION_RED`	Do not provision	If any participant designates `DECISION_RED`, the token is not provisioned and the cardholder is informed that the tokenization request failed.

Activation is handled differently, depending on the approval flow:

In the green approval flow, you typically receive the token activation request and activation transition within a few minutes of each other, without any further intervention.
In the yellow approval flow, the same two events are sent, but you receive the activation transition only after successful step-up verification.
In the red approval flow, no activation webhook is sent.

For cards in the yellow approval flow, you can perform step-up verification using one of these methods:

In-app verification: Your app verifies the cardholder’s identity using your own business logic. You make an API call to transition the digital wallet token, based on the verification decision you reach.
One-time passcode: The Marqeta platform sends a verification passcode to the cardholder using email or SMS; the cardholder enters the passcode into the digital wallet for identity verification. The Marqeta platform transitions the digital wallet token to ACTIVE.
Over-the-phone verification: The cardholder calls in to your call center or interactive voice response (IVR) system, which verifies their identity. You make an API call to transition the digital wallet token, based on the verification decision you reach. This verification method cannot be used concurrently with the Access code in authorization message method.
Access code in authorization message: The card network generates an access code, then posts a small authorization transaction to the cardholder’s account that includes the access code in the card_acceptor field. The cardholder logs in to their online banking application to retrieve the code, then enters the access code into the digital wallet for identity verification. The Marqeta platform transitions the digital wallet token to ACTIVE. This verification method cannot be used concurrently with the Over-the-phone verification method.

Risk control

The Marqeta platform offers several methods of mitigating the risk of fraudulent card use:

3D Secure adds multi-factor authentication to reduce the risk associated with card-not-present transactions. Acquirer support is growing primarily due to liability shift.
Real-Time Decisioning lets you create rule sets to assess the risk of transactions in real time, combining your own business logic and card network risk scores. You can use the resulting risk score in JIT Gateway funding request decisions.
Physical card controls ensure that physical cards are activated only by their intended users through PCI-compliant web widgets or IVR. Further protect physical cards with chips (EMV) and PINs.
Reporting lost or stolen cards to prevent unauthorized use. Cardholders have the tools to automatically lock their cards through your user interface and the Marqeta APIs.
Cardholders are protected from card theft and merchant fraud with chargeback protection.

3D Secure

3D Secure adds an additional layer of authentication to e-commerce transactions, and is mandated as part of Strong Customer Authentication (SCA) in the UK/EU. In the US, 3D Secure is not mandated but is recommended for international e-commerce transactions. Marqeta offers three policies for how you can configure 3DS to meet the needs of your business:

Challenge all: Issues a strong customer authentication challenge for all 3D Secure transactions. This is the most regulation-compliant option.
Delegated decisioning: Allows you to control authentication decision-making.
Automated decisioning: Allows you to configure a bespoke 3DS solutions without having to build or host it yourself.

Marqeta also offers two methods of authentication if 3DS is required:

Default OTP: Marqeta’s One-time Passcode (OTP) method is the default authentication option if you do not want to use your own authentication mechanism. In order for a user to receive the OTP, the user object must have the user’s email and phone number associated with it. You can add the user’s email and phone information directly using the email and phone fields in the user object. The user’s email address must be unique to the user. If multiple user objects contain the same email address, add the metadata.notification_email field to each user object.
Advanced authentication: Advanced authentication allows you to implement your own customized method of cardholder authentication, including in-app and biometric authentication.

Real-Time Decisioning

Real-Time Decisioning lets you apply business-rule-based granular controls to card transactions. Marqeta’s Real-Time Decisioning provides a dashboard you can use to create business rules to apply when making transaction authorization decisions. Marqeta has preset rules that you can obtain from your Marqeta representative, or you can choose to write your own rules. Real-Time Decisioning has a risk engine that executes business rules in the authorization flow in real time, deciding whether or not to approve, decline, or generate an alert on a transaction authorization. The business rules flag the transaction authorization when one or more rule is violated, and the results are passed through in the transaction JSON payload. For Gateway JIT Funding programs, Marqeta sends this information to your JIT Funding gateway for you to use in your own decisioning process. If a false positive is triggered, you can send a confirmation alert to the cardholder and then use the fraud feedback API to overrule the decision.

Disputes

Transaction disputes are a necessary part of card issuing. Marqeta enables you to manage the dispute process using either the Marqeta Dashboard or the /cases endpoint. You can manage disputes by performing tasks such as submitting a dispute, retrieving information such as dispute status, and uploading supporting documents.

Online refunds

Online refunds allow merchants with Visa and Mastercard to give their customers earlier notification of pending refunds. They also give issuers the opportunity to decline the refund. Online refunds are disabled by default for Marqeta customers, but can be enabled depending on your use case. When enabled, refund authorizations will be cleared with a refund authorization clearing and automatically processed in a manner similar to “offline” refunds. Gateway JIT lets you approve or decline refund authorizations. The following Gateway JIT Funding message and webhook events distinguish online refunds from offline refunds:

refund.authorization is sent in Gateway JIT Funding messages to indicate an online refund.
refund.authorization.clearing is a webhook event that indicates that an online refund has cleared.
refund.authorization.reversal is a webhook event that indicates that an online refund has been reversed.

For more information, ask your Marqeta representative for access to the Online Refunds Customer Guide.

Simulating transactions

Marqeta provides the Simulations API as a convenient way to create simulated transactions that will generate JIT Funding and webhook messages that you can use to test your integration. Simulated transactions do not integrate with card networks or result in any actual movement of funds. The Simulations API is only available in your sandbox environments. Listed below are some of the most common transactions you should simulate during your testing phase:

API Action and Endpoint	Description
`POST /simulations/cardtransactions/authorization`	Simulates an authorization.
`POST /simulations/cardtransactions/authorization.advice`	Simulates an advice adjustment to an authorization.
`POST /simulations/cardtransactions/authorization.clearing`	Simulates a clearing event for an authorization.
`POST /simulations/cardtransactions/authorization.reversal`	Simulates a reversal event for an authorization.

Transaction example

This section presents a walkthrough of the sequence of actions that occur during a typical authorization-and-clearing card transaction.

Authorization

Your Gateway JIT Funding integration with Marqeta plays an active role in authorization decisions at the time of purchase:

A cardholder makes a purchase using a card issued by your program.

The merchant sends an authorization request from their point of sale through the card network to the Marqeta platform.

Marqeta verifies the transaction against the bank-level rules established for your card program, including merchant category code restrictions, merchant identifier restrictions, spend limits, and accepted countries.

If the authorization is approved, Marqeta sends a JIT Funding request to your JIT Funding gateway endpoint.

Your JIT Funding gateway makes a funding decision based on criteria you have defined for your card program, such as:

User-level spend controls
Current user balance
Merchant details, such as the merchant name, category code, and identifier
Location of purchase

Your JIT Funding gateway endpoint issues one of two possible responses, along with required jit_funding message object:

HTTP 200 (approved)
HTTP 402 (declined)

Marqeta responds to the merchant through the card network with your authorization decision.

Upon completion of the transaction, Marqeta sends you the authorization webhook with the transaction details.

Your system updates the account ledger for the cardholder’s account to place a temporary hold on the authorized transaction amount.

Clearing

The merchant initiates a clearing transaction after a purchase has been fulfilled. The clearing transaction causes funds from your bank account to move to the merchant’s bank account to complete the transaction. Marqeta handles clearing and settlement on your behalf, but you must update your ledger to reflect the finalization of the transaction.

The merchant sends a clearing request to Marqeta through the card network.

Marqeta settles the cleared transaction, moving funds from your funding account to the card network for disbursement to the merchant.

Marqeta sends the authorization.clearing webhook event to your system.

Your system updates the ledger to reflect the appropriate adjustment of the completed transaction.

Preparing for production deployment

Once your sandbox integration is functionally complete and testable, you will work with your Solutions Engineer to determine your program’s readiness for the next stage of technical implementation with Marqeta’s Delivery Tech team.

Technical readiness

In order to gain access to production, you must complete the following tasks:

JIT certification
Environment review

When Marqeta has determined that you have successfully completed these tasks, you will receive your production environment API keys.

JIT certification

The purpose of JIT certification is to test authorizations against your sandbox JIT Funding gateway endpoint to validate the response mode in each of the scenarios listed below. The JIT certification process usually takes between one and two weeks to complete. The following must be true before JIT certification can begin:

Your sandbox JIT Funding gateway endpoint must be functional.
You must have completed testing approximately half of the required simulations.
Your JIT Funding gateway responses must be configured as described in the Gateway JIT Funding Messages API reference.

Environment review

In the environment review, Marqeta examines your sandbox environment to ensure that its various objects have been created correctly. The environment review process usually takes between one and two weeks to complete. The following must be true before the environment review can begin:

Your production IP addresses must be scanned and added to the allow list. This step usually takes between three and five business days.
Your testing and transaction simulations must be completed.
Your alignment form must be completed.

Tasks and milestones

The tasks and milestones listed below indicate the main steps leading to your production implementation. Early progress you make toward these goals will ensure a faster and more seamless production launch.

Review the Postman collection and technical assessment with your Solutions Engineer:

Walk through the cardholder onboarding process for your web or mobile app.
Send Marqeta all your source IP addresses that will connect to your private sandbox.

Become familiar with the public sandbox:

Understand and allocate the “good funds” model of six-day spend.
Understand user and card creation using the Postman collection.

Review the Marqeta tools suite with your Solutions Engineer:

Marqeta Dashboard
Network files
DiVA reporting

Begin ledger management development work:

Simulate transactions in your private sandbox.
Implement a simple application using ngrok, and use that application to send test transactions to your JIT Funding gateway endpoint.
Read and understand the Ledger Management with JIT Funding guide.
Draft your ledger management database and app schema for Gateway JIT Funding in your private sandbox.
Decide if you want to use Marqeta’s stand-in processing feature, Commando Mode.

Refund behavior:

Read and understand the Enabling Online Refunds guide.
Inform your Solutions Engineer if you plan to enable online refunds.
Inform your Solutions Engineer if you plan to use your Gateway JIT Funding implementation to review pgfs.refund.authorization messages, which are not enabled by default.

AVS behavior:

Read and understand the About Address Verification guide.
Inform your Solutions Engineer of your preferred address verification system.
Inform your Solutions Engineer if you choose to use your Gateway JIT Funding implementation to review pgfs.authorization.account_verification messages, which are not enabled by default.

Gateway JIT Funding setup for private sandbox:

Set up your private sandbox JIT Funding gateway endpoint.
Send the required information to your Solutions Engineer.
Simulate transactions in your private sandbox.
Begin testing ledger management for your private sandbox.

marqeta.js and card activation widgets (non-US card programs):

Explore widget features using the Marqeta Widget Style Preview page to determine the look and feel for your widgets.
Design widget customization and provide your design details to your Solutions Engineer.

Final preparation for delivery kickoff:

Review your sandbox environment.
Review transactions that will be submitted for JIT certification.
Review the hand-off expectations with your Solutions Engineer.

Guides

​Overview

​Prerequisites

​Technical overview

​Components

​Businesses, users, cards, and accounts

​JIT Funding gateway

​Ledger management

​Design principles for your Marqeta integration

​Resources

​Integration environments

​API visualizations

​Gateway JIT Funding implementation sample code

​Developer documentation

​Building and testing your card program

​Card products and account holder groups

​Business management

​About the Business KYC process

​User management

​Managing card-holding users

​Card product and card management

​PCI DSS compliance

​Managing cards

​Spend control management

​Authorization controls

​Velocity controls

​Gateway JIT Funding implementation

​Managing Gateway JIT Funding

​Webhooks and ledger management

​About webhooks

​Ledger management

​Dual-message transaction scenarios

​Single-message transaction scenarios

​Error handling

​Amounts

​Managing an account ledger

​Reporting

​Marqeta Dashboard

​DiVA API

​Settlement and reconciliation

​Tokenization

​Provisioning methods

​Digital wallet token lifecycle

​Digital wallet token provisioning approval flows

​Risk control

​3D Secure

​Real-Time Decisioning

​Disputes

​Online refunds

​Simulating transactions

​Transaction example

​Authorization

​Clearing

​Preparing for production deployment

​Technical readiness

​JIT certification

​Environment review

​Tasks and milestones

Overview

Prerequisites

Technical overview

Components

Businesses, users, cards, and accounts

JIT Funding gateway

Ledger management

Design principles for your Marqeta integration

Resources

Integration environments

API visualizations

Gateway JIT Funding implementation sample code

Developer documentation

Building and testing your card program

Card products and account holder groups

Business management

About the Business KYC process

User management

Managing card-holding users

Card product and card management

PCI DSS compliance

Managing cards

Spend control management

Authorization controls

Velocity controls

Gateway JIT Funding implementation

Managing Gateway JIT Funding

Webhooks and ledger management

About webhooks

Ledger management

Dual-message transaction scenarios

Single-message transaction scenarios

Error handling

Amounts

Managing an account ledger

Reporting

Marqeta Dashboard

DiVA API

Settlement and reconciliation

Tokenization

Provisioning methods

Digital wallet token lifecycle

Digital wallet token provisioning approval flows

Risk control

3D Secure

Real-Time Decisioning

Disputes

Online refunds

Simulating transactions

Transaction example

Authorization

Clearing

Preparing for production deployment

Technical readiness

JIT certification

Environment review

Tasks and milestones