Environments & Deployment

The MIDSuite Client API provides two environments to support development, testing, and production use. Integrations should begin in the sandbox environment and transition to production once implementation and testing are complete.

Both environments expose the same API surface and use identical request and response formats. The only difference is the base URL and the behavior of external integrations.

Sandbox Environment

The sandbox environment is designed for development and integration testing.

Base URL

https://api.sandbox.midsuite.com

The sandbox environment simulates API responses without performing real external checks. Requests are validated for proper structure and required fields. If the request passes validation, the API returns a successful response consistent with the expected structure of the corresponding production response.

Key characteristics of the sandbox environment:

• Performs request validation

• Returns simulated responses

• Does not execute real fraud, identity, or risk checks

• Transactions are not billed

• Completely isolated from production systems and data

Because the sandbox environment mirrors the production API interface, applications developed against sandbox can be promoted to production with minimal changes.

Sandbox Behavior

The sandbox environment simulates realistic payment validation responses to help developers test integrations before deploying to production. Responses returned by the PreCheck service vary deterministically based on the card number, CVV2 value, and address fields supplied in the request.

This allows integrators to reliably test different validation scenarios without using real card data.

Advice Responses

The preCheckResponse.advice field indicates the overall decision for a request.

General behavior

In most cases, the returned advice is determined by the CVV2 validation result:

• If cvv2Result is MATCH, the sandbox returns ACCEPT.

• If cvv2Result is anything other than MATCH, the sandbox returns DECLINE.

This mirrors common real-world issuer behavior where transactions are frequently declined when the CVV2 value does not match.

Special test card numbers

Specific sandbox card numbers override the general behavior and force a particular advice value:

These card numbers can be used to test how your integration handles various decision outcomes.

CVV2 Results

The preCheckResponse.cvv2Result field reflects the outcome of the CVV2 validation.

General behavior

• Even CVV2 values return MATCH

• Odd CVV2 values return NO_MATCH

• If CVV2 is omitted, the result will be NOT_PROVIDED

This allows easy testing of both successful and failed CVV validation scenarios.

Special CVV2 values

Certain CVV2 values force additional response types:

These values allow testing of edge cases that may occur with some issuers.

AVS Results

The sandbox simulates Address Verification Service (AVS) behavior using both the street address and postal code provided in the request.

The final AVS result returned by the API is derived from whether the street and postal code match:

Street match logic

If the street address begins with a numeric value and that number is even, the sandbox considers the street to match. Otherwise it is treated as a mismatch.

Postal code match logic

If the postal code (after removing non-numeric characters) is an even number, the sandbox treats the postal code as a match. Otherwise it is treated as a mismatch.

Testing Recommendations

When testing in the sandbox environment you can combine these inputs to simulate a wide variety of scenarios, including:

• successful card validations

• CVV mismatch declines

• AVS partial matches

• issuer-style validation failures

• retry or error handling logic

Because the sandbox behavior is deterministic, using the same inputs will always produce the same response, making it easier to automate integration tests.

Production Environment

The production environment executes real fraud detection, risk analysis, and identity verification services.

Base URL

https://api.midsuite.com

Before production access is granted, clients must complete the MIDSuite onboarding process, which includes:

• Contract onboarding

• Account creation

• KYC verification

• Billing configuration

Once the account is approved, API keys for the production environment can be created from the MIDSuite Merchant Portal.

Merchant Portal:

https://portal.midsuite.com

Production API keys must be included in the X-API-KEY request header for all API requests.

Go-Live Checklist

Before switching an integration from sandbox to production, verify the following:

1. Update the API base URL

   Replace the sandbox base URL with the production endpoint.

   https://api.sandbox.midsuite.com
   → https://api.midsuite.com

   plaintext

2. Replace the API key

   Ensure the application uses a production API key generated from the Merchant Portal.

3. Verify error handling

   Confirm the integration correctly handles validation errors, service failures, and unsuccessful responses.

4. Validate retry logic

   Ensure retry behavior is safe and avoids duplicate transaction processing where applicable.

5. Confirm PCI compliance practices

   Verify that sensitive payment data is handled and stored in accordance with PCI requirements.

Versioning Strategy

The MIDSuite API uses URL-based versioning.

Current version:

/api/v1/

Example endpoints:

POST /api/v1/precheck
POST /api/v1/rules
POST /api/v1/sentry
POST /api/v1/idverify
POST /api/v1/pipeline

Versioning policies:

• The current version (v1) will remain stable indefinitely.

• Changes within a version are additive only and will not introduce breaking changes.

• Breaking changes will be released under a new version (for example /api/v2/).