DOCS
Developer resources
Community

Collaborate on your project with other Marqeta developers

Sales

Speak with an expert to learn more about Marqeta

/
Guides
Core API

Launch and manage your company's payment card program

Core API Reference

Endpoint definitions and field-level reference

Core API Explorer

Try out all endpoints from your browser

DiVA API

Access the production data behind Marqeta's reporting and analytics tools

DiVA API Reference

Endpoint definitions and field-level reference

15 minute read
April 18, 2023

Transaction Data for JIT Funding Decisions

If you have enabled Gateway Just-in-Time (JIT) Funding for your program, the Marqeta platform sends funding requests to your system for each transaction. Some transaction types, such as authorizations, are actionable, meaning your system must respond programmatically to the request and approve or deny the funding. Other transaction types, such as refunds or reversals, are informative only, meaning your system receives a funding notification but does not need to send a response.

To aid in your system’s decisioning process, the Marqeta platform includes data in the request about the transaction being funded. This data describes aspects of the transaction that indicate to your system whether it is advisable to approve or deny the funding request.

The message sent to your JIT Funding gateway endpoint includes the following key objects for decisioning:

  • jit_funding

  • fraud

  • cardholder_authentication_data

  • card_security_code_verification

  • transaction_metadata

In addition to your system’s programmatic responses to JIT Funding requests, you can configure the following restrictions for your program on the Marqeta platform:

  • Spend controls — Limits when, where, and how much a user can spend with their card. For more information, see Controlling Spending.

  • Address Verification System (AVS) — Verifies that the address provided by the cardholder matches the address on file. For more information, see About Address Verification.

The Marqeta platform processes these restrictions before sending a JIT Funding request to your gateway endpoint.

JIT Funding
Copy section link

The jit_funding object contains information about the funding event, including the associated user token and transaction amount. The method field indicates the type of transaction and whether the message is an actionable funding request sent to your gateway endpoint or an informative message sent to your webhook endpoint.

Actionable transaction types
Copy section link

Your system must programmatically approve or deny JIT Funding requests for the following types of transactions:

  • pgfs.authorization

  • pgfs.authorization.incremental

  • pgfs.auth_plus_capture

  • pgfs.billpayment

  • pgfs.billpayment.capture

  • pgfs.original.credit.authorization

  • pgfs.original.credit.auth_plus_capture

For more information about the jit_funding object, as well as the differences between actionable and informative transaction types, see Gateway JIT Funding Messages.

Fraud
Copy section link

The fraud object contains fraud-related data elements from the card network and the Marqeta platform when Real-Time Decisioning is enabled.

issuer_processor object
Copy section link

The issuer_processor object is part of the fraud object in the /transactions endpoint.

Fields Description

score

integer
Conditionally returned

The risk score generated by RiskControl. This is either the Mastercard Decision Intelligence or Visa Advance Authorization transaction risk score, which is identical to the network_transaction_risk_score field.

Allowable Values:

0 - 99

risk_level

string
Conditionally returned

The fraud rating, or level of risk for the transaction.

Allowable Values:

high, low

rule_violations

array of strings
Conditionally returned

The rules violated by the transaction.

Allowable Values:

Valid array of one or more rule violations

recommended_action

string
Conditionally returned

The action recommended based on the fraud score.

Allowable Values:

APPROVE, DECLINE, NOT_PERFORMED

riskcontrol_tags

array of objects
Conditionally returned

The RiskControl tags triggered by the transaction.

Allowable Values:

See the riskcontrol_tags object.

fraud_score_reasons

array of strings
Conditionally returned

Reasons for the fraud score.

Allowable Values:

Valid array of one or more fraud score reasons

triggered_rules

array of objects
Conditionally returned

Rules triggered by the event.

Allowable Values:

See the triggered_rules object.

riskcontrol_tags object
Copy section link

Note
This object will be deprecated in the future. Instead, use the triggered_rules object.

When a rule from your own custom-defined operational models is triggered, it generates a tag for your downstream actions. This information, including the tag, rule name, and associated multiple values, is contained in the riskcontrol_tags object as part of the fraud object in the /transactions endpoint.

Fields Description

values

array of strings
Conditionally returned

Values associated with the tag.

Allowable Values:

Valid array of one or more tag values

tag

string
Conditionally returned

Tag name defined in the rule definition in the Real-Time Decisioning dashboard.

Allowable Values:

255 char max

rule_name

array of strings
Conditionally returned

Name of the rule as defined in the Real-Time Decisioning dashboard that was triggered.

Allowable Values:

255 char max

triggered_rules object
Copy section link

This object provides a list of rules triggered by a fraud event along with the information on tags and rule characteristics.

Fields Description

rule_name

string
Conditionally returned

Name of the rule as defined in the Real-Time Decisioning dashboard that was triggered.

Allowable Values:

255 char max

tags

array of objects
Conditionally returned

All the tags defined in the triggered rule.

Allowable Values:

See the tags object.

alert

boolean
Conditionally returned

Indicates if the rule triggered an alert.

Allowable Values:

true, false

entity_type

string
Conditionally returned

The entity type where the triggered rule was defined.

Allowable Values:

Valid entity type

suppress_alert

boolean
Conditionally returned

Indicates if the triggered rule has suppress_alert in the definition.

Allowable Values:

true, false

tags object
Copy section link

This object provides a list of tags along with the names and values defined in the triggered rules.

Fields Description

name

string
Conditionally returned

Name of the tag.

Allowable Values:

255 char max

value

string
Conditionally returned

Value of the tag.

Allowable Values:

255 char max

The following code block shows a sample fraud object as it would appear in a JIT Funding request:

JSON
Copied

Is this helpful?

Yes
No

Cardholder authentication data
Copy section link

The cardholder_authentication_data object contains information about additional authentication performed for e-commerce transactions. For example, a transaction participant (such as the card network) can request additional verification during the transaction process, such as the cardholder’s name or date of birth.

Fields Description

acquirer_exemption

array of strings
Conditionally returned

Indicates 3D Secure authentication exemptions from the acquirer. This array is returned if it is included in the transaction data from the card network.

Allowable Values:

MERCHANT_INITIATED_TRANSACTION, TRANSACTION_RISK_ANALYSIS, RECURRING_PAYMENT, LOW_VALUE_PAYMENT, SCA_PERFORMED, SECURE_CORPORATE_PAYMENT, AUTHENTICATION_OUTAGE_EXCEPTION

authentication_method

string
Conditionally returned

Specifies the 3D Secure authentication method.

Allowable Values:

null, AUDIO_CALL, BEHAVIORAL_BIOMETRICS, BIOMETRIC, BIOMETRIC_FACE, BIOMETRIC_FINGERPRINT, DECOUPLED, DELEGATED_TRUSTED_AUTHENTICATION, FRICTIONLESS, IN_APP_LOGIN, KNOWLEDGE_BASED, OOB, OOB_OTHER, OTHER, OTP, OTP_SMS, OTP_EMAIL, SECURE_PAYMENT_CONFM, VIDEO_CALL, VOICE_RECOGNITION, WEB_AUTHN, OTHER

authentication_status

string
Conditionally returned

Specifies the status of the 3D Secure authentication.

  • ATTEMPTED: Indicates that 3D Secure authentication was requested and processed by the card network.

  • DATA_SHARE_EXEMPTION: Indicates that 3D Secure authentication was for information only and exempted.

  • EXEMPTED: Indicates that 3D Secure authentication was requested but the challenge was exempted.

  • EXEMPTION_CLAIMED: Indicates that 3DS Secure authentication was exempted because acquirer transaction risk analysis (TRA) was already performed.

  • SCA_EXEMPTION: Indicates that 3D Secure authentication was exempted because strong customer authentication (SCA) was already performed.

  • SUCCESSFUL: Indicates that 3D Secure authentication was successful.

  • SUCCESSFUL_NON_PAYMENT: Indicates that 3D Secure non-payment authentication was successful.

  • THREEDS_REQUESTER_DATA_SHARE_EXEMPTION: Status is deprecated and will be removed from a future release of the Marqeta platform. After June 2023, use DATA_SHARE_EXEMPTION instead.

  • THREEDS_REQUESTER_SCA_EXEMPTION: Status is deprecated and will be removed in a June 2023 release of the Marqeta platform. After June 2023, use SCA_EXEMPTION instead.

  • THREEDS_REQUESTER_TRA_EXEMPTION: Status is deprecated and will be removed in a June 2023 release of the Marqeta platform. After June 2023, use EXEMPTION_CLAIMED instead.

  • UNAVAILABLE:

    • For Visa transactions, this status indicates that 3D Secure authentication was requested, but Marqeta’s access control server (ACS) was not available.

    • For Mastercard transactions, this status indicates that 3D Secure authentication was not available.

Allowable Values:

ATTEMPTED, DATA_SHARE_EXEMPTION, EXEMPTION_CLAIMED EXEMPTED, SCA_EXEMPTION, SUCCESS, SUCCESSFUL_NON_PAYMENT, THREEDS_REQUESTER_DATA_SHARE_EXEMPTION, THREEDS_REQUESTER_SCA_EXEMPTION, THREEDS_REQUESTER_TRA_EXEMPTION, UNAVAILABLE

electronic_commerce_indicator

string
Conditionally returned

Status of the 3D Secure authentication attempt, as provided by a transaction participant.

  • authentication_attempted: Merchant attempted to authenticate, but either the issuer or the cardholder does not participate in 3D Secure.

  • authentication_successful: Cardholder authentication successful.

  • no_authentication: Non-authenticated e-commerce transaction.

Allowable Values:

authentication_attempted, authentication_successful, no_authentication

three_ds_message_version

string
Conditionally returned

Specifies the 3D Secure message version used for authentication.

Allowable Values:

1.0.2, 2.1.0, 2.2.0

verification_result

string
Conditionally returned

Result of the cardholder authentication verification value (CAVV) or accountholder authentication value (AAV) verification performed by the card network.

  • failed

  • not_present

  • not_provided

  • not_verified

  • not_verified_authentication_outage

  • verified

  • verified_amount_greater_than_20_percent: For Mastercard AAV verification, indicates that the original authentication amount and final authorization amount are mismatched, and that the final authorization amount is greater than 20% of the original authentication amount. This 20% margin falls outside Mastercard’s suggested tolerance for what a European cardholder might reasonably expect when the total transaction amount is not known in advance.

  • verified_amount_greater_than_20_percent: For Mastercard AAV verification, indicates that the original authentication amount and final authorization amount are mismatched, and that the final authorization amount exceeds the original authentication amount by more than 20%. This 20% margin falls outside Mastercard’s suggested tolerance for what a European cardholder might reasonably expect when the total transaction amount is not known in advance.

  • verified_amount_less_than_20_percent: For Mastercard AAV verification, indicates that the original authentication amount and final authorization amount are mismatched, and that the final authorization amount exceeds the original authentication amount by 20% or less. This 20% margin falls within Mastercard’s suggested tolerance for what a European cardholder might reasonably expect when the total transaction amount is not known in advance.

Allowable Values:

failed, not_present, not_provided, not_verified, not_verified_authentication_outage, verified, verified_amount_greater_than_20_percent, verified_amount_less_than_20_percent

verification_value_created_by

string
Conditionally returned

Transaction participant who determined the verification result. This field is only available for Visa transactions.

Allowable Values:

issuer_acs, issuer_attempts_server, network, network_attempts_server

The following code block shows a sample cardholder_authentication_data object as it would appear in a JIT Funding request:

JSON
Copied

Is this helpful?

Yes
No

Card network field data for cardholder authentication
Copy section link

We include these tables of cardholder authentication field data for the Mastercard and Visa card networks to help clarify the cardholder authentication data results you may see in JIT Funding transactions.

Mastercard field data
Copy section link

This table shows cardholder authentication field data from the Mastercard network.

Security Level Indicator (SLI) Secure Payment Application Version 2 (SPA2) Electronic Commerce Indicator Verification Method Verification Status Verification Value Created By

210

N/A

no_authentication

N/A

UNAVAILABLE

N/A

211

kE

authentication_attempted

N/A

ATTEMPTED

network_attempts_server

211

kF

authentication_attempted

N/A

ATTEMPTED

network_attempts_server

212

kA

authentication_successful

FRICTIONLESS

EXEMPTED

issuer_acs

212

kC

authentication_successful

STANDIN_FRICTIONLESS

EXEMPTED

network

212

kB

authentication_successful

CHALLENGE

SUCCESSFUL

issuer_acs

212

kR

authentication_successful

FRICTIONLESS

EXEMPTED

issuer_acs

212

kS

authentication_successful

OOB_OTHER

SUCCESSFUL

issuer_acs

212

kD

authentication_successful

IDENTITY_CHECK_EXPRESS

SUCCESSFUL

network

212

kQ

authentication_successful

FRICTIONLESS

EXEMPTED

issuer_acs

214

N/A

no_authentication

N/A

THREEDS_REQUESTER_DATA_SHARE_EXEMPTION

N/A

216

kN

no_authentication

N/A

THREEDS_REQUESTER_SCA_EXEMPTION

issuer_acs

217

kO

authentication_successful

FRICTIONLESS

EXEMPTED

issuer_acs

217

kP

authentication_successful

CHALLENGE

SUCCESSFUL

issuer_acs

Visa field data
Copy section link

This table shows cardholder authentication field data from the Visa network.

CAVV Description Consideration Verification Result Verification Value Created By

Blank

CAVV not present in authorization message

Field 126.9 is empty

not_present

N/A

Blank

CAVV not verified, issuer has not selected CAVV verification option

Field 126.9 is not empty

not_verified

N/A

0

CAVV could not be verified

Field 126.9 is not empty

not_verified

N/A

0

CAVV data was not provided when expected

Field 126.9 is empty

not_provided

N/A

1

CAVV failed verification – cardholder authentication

CAVV was created by the issuer’s Attempts Server

failed

issuer_acs

2

CAVV passed verification – cardholder authentication

CAVV was created by the issuer’s Attempts Server

verified

issuer_acs

3

CAVV passed verification – attempted authentication

CAVV was created by the issuer’s Attempts Server

verified

issuer_attempts_server

4

CAVV failed verification – attempted authentication

CAVV was created by the issuer’s Attempts Server

failed

issuer_attempts_server

5

Reserved – not in use

N/A

N/A

N/A

6

CAVV not verified, issuer not participating in CAVV verification

CAVV can be created by the issuer’s ACS, issuer’s Attempts Server, or Visa Attempts Service

not_verified

network

7

CAVV failed verification – attempted authentication

CAVV was created by Visa’s Attempts Service

failed

network_attempts_server

8

CAVV passed verification – attempted authentication

CAVV was created by Visa’s Attempts Service—Non-participating issuer or cardholder

verified

network_attempts_server

9

CAVV failed verification – attempted authentication

CAVV was created by Visa’s Attempts Service—Issuer ACS was not available

failed

network_attempts_server

A

CAVV passed verification – attempted authentication

CAVV was created by Visa’s Attempts Service—Issuer ACS was not available

verified

network_attempts_server

B

CAVV passed verification – no liability shift

CAVV was processed but the transaction does not qualify for Visa’s 3-D Secure program

verified

network

C

CAVV was not verified - attempted authentication

CAVV was created by the issuer’s Attempts Server

not_verified

issuer_attempts_server

D

CAVV was not verified – cardholder authentication

CAVV was created by the issuer’s ACS

not_verified

issuer_acs

Card security code verification
Copy section link

The card_security_code_verification object contains information about a verification check performed on the card’s security code.

The type field indicates the type of security code and can have the following possible values:

  • CVV1 – The security code stored in the magnetic stripe on the card.

  • CVV2 – The security code printed on the card.

  • ICVV – The security code stored on the chip of the card.

  • DCVV – A dynamic security code used in some contactless payments when a card or device is tapped on the card reader.

The response.code field indicates whether the verification check passed and can have one of the following values:

  • 0000 – Passed

  • 0001 – Did not pass

Fields Description

type

string
Returned

Type of security code verified.

Allowable Values:

CVV1, CVV2, ICVV, DCVV

response.code

string
Returned

Indicates whether the verification check passed.

Allowable Values:

0000, 0001

response.memo

string
Conditionally returned

Free-form description of the verification result, as provided by a transaction participant.

Allowable Values:

99 char max

The following code block shows a sample card_security_code_verification object as it would appear in a JIT Funding request:

JSON
Copied

Is this helpful?

Yes
No

Transaction metadata
Copy section link

The transaction_metadata object contains additional merchant-provided details about a transaction. It also includes sub-objects for more detailed information about transit and air travel purchases.

Note
Transaction metadata is only included when provided by the merchant.
Fields Description

transaction_category

string
Conditionally returned

Type of product or service being purchased, if provided by the merchant.

Allowable Values:

RETAIL_SALE, BILL_PAY, HOTEL, RESTAURANT, AUTO_RENTAL, AIRLINE, PAYMENT, HOSPITALIZATION_COLLEGE, PHONE_MAIL_ECOMMERCE, ATM, HEALTH_CARE, TRANSIT

authorization_life_cycle

integer
Conditionally returned

Number of days until pre-authorization expires, if provided by the merchant.

Allowable Values:

lodging_auto_rental_start_date

date
Conditionally returned

Pick-up date for an auto rental, or check-in date for lodging, if provided by the merchant.

Allowable Values:

The transaction_metadata.transit sub-object can contain the following fields related to transportation other than air travel:

Fields Description

transaction_type

string
Conditionally returned

Type of transit transaction performed, if provided by the merchant.

Allowable Values:

PRE_FUNDED, REAL_TIME_AUTHORIZED, POST_AUTHORIZED_AGGREGATED, AUTHORIZED_AGGREGATED_SPLIT_CLEARING, OTHER, DEBIT_RECOVERY

transportation_mode

string
Conditionally returned

Mode of transportation purchased, if provided by the merchant.

Allowable Values:

BUS, TRAIN, WATER_BORNE_VEHICLE, TOLL, PARKING, TAXI, PARA_TRANSIT, SELF_DRIVE_VEHICLE, COACH, LOCOMOTIVE, POWERED_MOTOR_VEHICLE, TRAILER, INTER_CITY, CABLE_CAR

The transaction_metadata.airline sub-object can contain the following fields related to air travel:

Fields Description

passenger_name

string
Conditionally returned

Name of passenger for air travel, if provided by the merchant.

Allowable Values:

Format: forename surname

depart_date

date
Conditionally returned

Date of departure for air travel, if provided by the merchant.

Allowable Values:

Format: dd/mm/yyyy

origination_city

string
Conditionally returned

Three-letter airport code for the city of departure, if provided by the merchant.

Allowable Values:

Format: SFO

The following code block shows a sample of the transaction_metadata object as it would appear in a JIT Funding request:

JSON
Copied

Is this helpful?

Yes
No

Related materials

Subscribe to our developer newsletter

© 2023 Marqeta, Inc.

• Terms • API Terms • Privacy • Cookies
Back to Marqeta.com