Getting Started

This section will walk you through making your first successful API call to MIDSuite.

The goal: authenticate correctly, send a valid request, and interpret the response.

Prerequisites

Before integrating with the MIDSuite Client API, ensure you have:

1. API Key Access

You must have an active MIDSuite account and a valid API key.

If you do not yet have API credentials, contact MIDSuite support or your account representative.

Your API key will be used in every request via the X-API-KEY header.

2. Network Access

MIDSuite provides two environments:

Use Sandbox for development and testing.
Use Production only after completing integration testing and go-live approval.

Authentication

All API requests require an API key sent in the request header:

X-API-KEY: your_api_key_here

Example

curl -X POST https://api.sandbox.midsuite.com/api/v1/precheck \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{ ... }'

Security Best Practices

• Store API keys securely (never commit to source control)

• Use environment variables or a secrets manager

• Rotate keys periodically

• Never expose API keys in client-side applications (browser or mobile)

All MIDSuite API calls should originate from your secure backend infrastructure.

Your First API Call

For your first request, we recommend using the PreCheck endpoint.

PreCheck validates card details and returns AVS/CVV results along with a recommended action.

Endpoint

POST /api/v1/precheck

Full URL (Sandbox):

https://api.sandbox.midsuite.com/api/v1/precheck

Example Request

{
  "clientReferenceId": "ORDER-10001",
  "cardNumber": "4111111111111111",
  "cardExpiryDate": "2040-10",
  "cardCvv2Value": "022",
  "cardAddress": {
    "postalCode": "94404",
    "street": "801 Metro Center Blvd"
  }
}

Required fields:

• cardNumber

• cardExpiryDate

Example Successful Response

{
  "isSuccess": true,
  "preCheckResponse": {
    "advice": "ACCEPT",
    "avsResult": "FULL_MATCH",
    "cvv2Result": "MATCH"
  },
  "errors": null,
  "billing": {
    "amountAuthorized": {
      "amount": 0.05,
      "currency": "USD"
    },
    "remainingBalance": {
      "amount": 99.95,
      "currency": "USD"
    }
  }
}

Understanding Success vs Failure

Every v1 endpoint follows a consistent response structure:

{
  "isSuccess": boolean,
  "errors": { ... },
  "billing": { ... },
  "<serviceResponse>": { ... }
}

isSuccess

• true → The request was processed successfully.

• false → The request failed validation or processing.

Note: An HTTP 200 status code does not always mean the business request succeeded. Always check isSuccess.

errors Object

If isSuccess is false, the errors object will provide details.

Structure:

{
  "message": "Validation failed",
  "fieldErrors": {
    "cardNumber": ["Card number is invalid"]
  },
  "globalErrors": [
    "Request could not be processed"
  ]
}

• fieldErrors → Field-specific validation issues

• globalErrors → Request-level failures

• message → High-level error description

Service-Level Decisions

Even when isSuccess = true, the service may return decisions requiring action.

For example, PreCheck may return:

• ACCEPT

• DECLINE

• RETRY

• FRAUD

• INPUT_ERROR

You should design your integration to:

1. Validate isSuccess

2. Inspect the service-specific response

3. Apply your business logic accordingly

Next Steps

After successfully calling PreCheck:

• Review the Core Concepts section to understand billing and client reference IDs.

• Explore individual service guides (PreCheck, Rules, Sentry, ID Verify).

• Consider using the Pipeline API if you need multi-stage orchestration.