How to test integration between a bank mainframe and APIs

Mainframe to API integration testing verifies that requests and responses crossing a bank's API boundary preserve their intended business meaning and transaction state in the mainframe and connected systems. It checks data mapping, business rules, security, error handling and consistency across synchronous calls, messaging or batch hand-offs, using controlled test data and observable outcomes.

Mainframe to API integration testing scope

A typical flow includes an API consumer, an API gateway or service layer, an adapter or middleware component, and a mainframe application or data store. The exact route depends on the bank's architecture. The API may call a mainframe transaction directly, send a message for later processing, or exchange data through a scheduled file.

Test the boundaries where data or control passes between these components. Check that field names, formats, lengths, character encoding, date and time conventions, currency precision and status codes map correctly. Confirm that business rules run in the expected system and that a successful API response reflects the actual processing outcome.

API contract testing checks that an interface follows its agreed schema and behaviour. Integration testing exercises that contract against the adapter and mainframe environment, so it can find issues such as an invalid host response mapping or a transaction that commits despite a client timeout.

Prepare the environment and test data

Agree which environment contains the mainframe application, middleware, API gateway and any downstream systems required for the flow. Record configuration and interface versions. Differences in routing, permissions, code pages or transaction definitions can make a test result differ from production behaviour, so check for environment drift before execution.

Use bank-approved, synthetic or suitably anonymised data. Create accounts and transactions in known states, and confirm that tests can reset or reverse their changes. Avoid shared records that concurrent tests or batch jobs can update. Capture the starting state and identify an authoritative source for checking the final result, such as a supported account enquiry, transaction history or ledger record.

Define expected behaviour for timeouts, retries and asynchronous processing before testing. For example, an API may return an accepted status while a message awaits processing. The test then needs to check the eventual transaction state, not treat the initial response as proof of completion.

Test the main integration paths

Cover a valid request, invalid or missing fields, boundary values, unauthorised access and downstream failures. Check both the API response and the resulting mainframe state. Include values that can be altered by mapping, such as long names, leading zeroes, negative amounts where allowed, and dates around a business-day boundary.

For a payment or transfer flow, verify that the debit and credit use the correct accounts and amount, that the transaction identifier is traceable across components, and that any required audit record is created. Check that a rejected request leaves no unintended partial posting. For a timeout after submission, establish whether the mainframe committed the transaction and confirm that a client retry cannot create an unintended duplicate. Test idempotency keys where the API contract supports them.

Also test response mapping for host errors and validation failures. The API should return the documented status and safe error detail, while operational logs retain enough correlation information for investigation. Check that sensitive account or customer data does not appear in responses or logs where it is not permitted.

Worked example: account transfer

Assume the API accepts a transfer request and the mainframe posts it synchronously. Use two test accounts with known balances and submit a transfer for a valid amount.

1. Record the opening balances and submit the request with a unique reference.
2. Check the HTTP status and response fields against the API contract, including the returned transaction reference.
3. Query the authoritative transaction record and both account balances. Confirm the debit, credit, amount and currency match the request and bank rules.
4. Submit the same request again if the contract defines safe retry behaviour. Confirm that the outcome follows that contract and does not create an unintended second posting.
5. Repeat with an invalid account or an amount outside the permitted limit. Confirm the documented error and verify that neither account has an unintended balance change.

For asynchronous processing, adapt the checks to wait or poll within an agreed time limit for a final status. Record a timeout as a failure to meet the expected behaviour, then inspect the transaction state before retrying or cleaning up test data.

Verify results and manage limitations

Use correlation identifiers to follow a request through API logs, middleware, message queues and mainframe records. Automated checks can run in a continuous integration (CI) pipeline when the required environments and test data are available. Keep evidence of request, response, final state and relevant logs, with sensitive values masked.

A stub or service virtualisation can help test API behaviour while the mainframe is unavailable. It cannot prove that the real adapter, host transaction or environment configuration works correctly. Run integration tests against the actual test mainframe before treating the end-to-end result as verified. Reconcile the API outcome with the mainframe's authoritative transaction state, especially for timeouts, retries and delayed processing.