Data Models & Field Semantics

The MIDSuite API uses a consistent set of data models across all services. While the API specification defines the exact schemas and field types, this section explains how those fields should be interpreted and used in real integrations.

Understanding these semantics helps ensure accurate fraud analysis, identity verification, and risk scoring.

Card Data Handling

Several services accept payment card data as part of the request. These fields are used only for evaluation and are not intended to be stored long-term by the API.

Card Number

The

cardNumber

field represents the full primary account number (PAN).

Expected format:

• Numeric string

• 13–19 digits

• No spaces or separators

Example:

"cardNumber": "4111111111111111"

Best Practices

• Transmit card numbers only over HTTPS.

• Do not log raw card numbers in application logs.

• If possible, use tokenized card numbers from your payment gateway.

• Only send card numbers when the service requires them.

Card Expiration Date

The expiration date uses a YYYY-MM format.

Example:

"cardExpiryDate": "2040-10"

This format avoids ambiguity and allows consistent parsing across systems.

CVV / CVV2

The CVV field appears in some requests as:

cardCvv2Value

Expected format:

• Numeric string

• Usually 3 or 4 digits

• Do not include spaces.

CVV should only be transmitted if your PCI compliance program allows it.

Address Formats & Normalization

Address data is used by several services for verification, scoring, and fraud detection.

Common address models include:

• CardAddress

• Billing

• Shipping

Although their schemas vary slightly, they follow the same general structure.

Typical fields include:

Country Codes

Country codes should follow the ISO-3166-1 alpha-2 format.

Example:

US
GB
CA
DE

Address Normalization

The MIDSuite platform may normalize or standardize address information internally. For best results:

• Provide complete addresses whenever possible

• Include postal code and country

• Avoid abbreviations when possible

More complete address information generally results in stronger fraud and identity signals.

Monetary Values & Currency Handling

Transactions and billing information may include monetary values.

These values are represented using the

Money

data model.

Example:

{
  "amount": 19.95,
  "currency": "USD"
}

Amount

• Decimal numeric value

• Must be non-negative

• Uses standard currency precision (usually two decimal places)

Currency

Currencies should be expressed using ISO-4217 currency codes.

Examples:

USD
EUR
GBP
JPY

Service Billing

Some responses include a

billing

object that contains:

• Total authorized amount

• Closed charges

• Remaining balance

• Individual invoice items

Each invoice item includes:

• fee

• feeType

• completion status

These records reflect API service usage charges.

Optional vs Required Fields

Each endpoint defines required fields, but most services allow additional contextual data to improve analysis.

Minimal Requests

A request only needs to include the required fields for the specific endpoint.

For example:

PreCheck minimum request

{
  "cardNumber": "4111111111111111",
  "cardExpiryDate": "2040-10"
}

Recommended Enrichment

Providing additional fields can significantly improve risk detection.

Examples:

While optional fields are not strictly required, supplying them improves scoring accuracy.

Enum Meanings and Constraints

Many API fields use enumerated values to represent decisions or verification outcomes.

Understanding these values is important for building reliable application logic.

Action & Decision Enums

Some services return decision-style values.

Example: PreCheck advice

ACCEPT
DECLINE
BAD_CARD
FRAUD
RETRY
INPUT_ERROR
TEMP_ERROR
ERROR
UNKNOWN

Typical interpretation:

Verification Result Enums

Identity verification responses often return match-style results.

Examples:

MATCH
PARTIAL_MATCH
NO_MATCH
NOT_PROCESSED
NOT_SUPPORTED
UNKNOWN

Typical meanings:

Risk Status Enums

Risk decisions returned by the Rules service include:

ACCEPT
REVIEW
DENY
INCOMPLETE
NO_MATCH

Typical interpretation:

General Field Conventions

The API follows several conventions across all services.

Boolean fields

Always returned as JSON booleans:

true
false

Example:

"isSuccess": true

Timestamps

Timestamps use ISO-8601 format in UTC.

Example:

2026-01-13T09:45:23.52Z

Identifiers

Fields such as:

clientReferenceId
transactionId
shopId
userId

are treated as opaque identifiers.

They:

• Are not interpreted by the API

• Are returned for correlation and traceability

• May be numeric or string-based

Summary

Understanding field semantics ensures that your integration sends consistent data and interprets results correctly.

Key recommendations:

• Use standard formats for card data, addresses, and currencies

• Provide as much contextual information as possible

• Treat enum responses as structured decision signals

• Preserve identifiers for logging and traceability

Correct data modeling significantly improves fraud detection accuracy and overall integration reliability.