This section explains the core ideas behind how the MIDSuite Client API works. Understanding these concepts will make it easier to design reliable integrations and interpret responses from the platform.

API Architecture Overview

The MIDSuite Client API follows a stateless, synchronous request/response model.

Stateless Requests

Each API request is evaluated independently. The server does not retain session state between calls, so every request must contain all the information necessary to evaluate the transaction.

This approach provides several advantages:

• High scalability

• Predictable behavior

• Simplified retry logic

• Compatibility with distributed systems and microservices

Clients should not assume that information from previous requests will be reused by the system.

Synchronous Evaluation

All API endpoints return a response immediately after evaluation. The results of the requested service are included directly in the response payload.

Typical flow:

1. Client sends a request to an endpoint (for example, PreCheck or Rules)

2. MIDSuite evaluates the request

3. The service result and billing information are returned in the response

No asynchronous polling or job processing is required.

Client Reference IDs

Many requests include an optional field called clientReferenceId.

This value is provided by the client system and serves as a client-defined identifier for the request.

Purpose

clientReferenceId exists primarily for traceability and support diagnostics. It allows clients to associate MIDSuite API calls with internal transactions, orders, or customer events.

Example uses include:

• Checkout transaction IDs

• Order numbers

• Internal fraud investigation references

• Customer support case identifiers

Uniqueness

The value does not need to be globally unique, but it is recommended that clients use identifiers that are unique within their own systems to simplify tracking.

Idempotency

clientReferenceId is not used for idempotency. Submitting the same value multiple times will not prevent the request from being processed again.

Support and Debugging

When contacting MIDSuite support regarding a request, providing the associated clientReferenceId can help quickly locate the relevant transaction.

Billing and Invoicing

Every successful API request returns billing information describing the cost of the services performed during that request.

Billing details appear in the billing object included in the API response.

midsuite-client-api

Billing Object

The billing object represents the invoice generated for the request and includes:

• amountAuthorized — Total amount authorized for the request

• amountClosed — Total amount charged after completed services are finalized

• remainingBalance — Remaining balance available on the account

• items — Individual line items describing each billed service

Billing data is calculated in real time for each request.

If a request fails due to validation or other errors, no billing information is returned and no charges occur.

Invoice Items

Each element in items represents a single service executed as part of the request.

Invoice items contain:

• feeType — The type of service performed

• fee — Cost associated with that service

• completed — Indicates whether the service completed successfully and should be included in the final closed amount

Common fee types include:

• PRECHECK

• PRECHECK_INT

• RULES

• SENTRY

• ID_VERIFY

• ID_VERIFY_INT

• GATEWAY

The *_INT variants represent pricing applied when processing international (non-US) cards.

Pipeline Billing

When using the Pipeline API, a single request may execute multiple services.

In these cases:

• The invoice contains one item for each executed service

• The amountAuthorized and amountClosed values represent the aggregate of all invoice items

• Services that are not executed are not billed

This allows the Pipeline API to provide a consolidated billing summary while still showing the cost of each individual stage.