OpenAPI contracts: designing a payment API contract

Before a developer writes a single line of code, a bank publishes a contract for its payment API. That contract is written in the OpenAPI Specification, a machine readable format that describes exactly what the API accepts, what it returns, and what can go wrong. It is usually a YAML or JSON file, and it is the single source of truth for the API. A developer reads it to build a client. A tester reads it to write test cases. A business analyst reads it to check that the API does what the business needs. If the contract is wrong, every system built on it will be wrong too. An OpenAPI contract has five parts. The paths list every endpoint, for example POST /payments for creating a payment and GET /payments/{id} for checking its status. The operations describe what each endpoint does, including the request body and the response body. The schemas define every field, its type, whether it is required, and its constraints, for example that the instructed amount must be a number with at least two decimal places and a minimum value of 0.01. The security section states how the caller authenticates, for example with an OAuth2 token or with mutual TLS. And the responses list every status code the API can return, with the error format for each one. The contract must state the error responses explicitly, because error handling is where most API integrations fail. A 400 bad request means the request was invalid, for example a missing mandatory field, and the response must name the missing field. A 401 unauthorised means the caller is not authenticated. A 404 not found means the payment identifier does not exist. A 409 conflict means the request conflicts with the current state, for example trying to cancel a payment that has already settled. A 500 internal error means the server failed. A developer who only reads the happy path will build a client that breaks on the first error, so the contract must make the errors as clear as the success. The contract must also state the idempotency rule. When a client sends a payment request, it includes an idempotency key in a header, for example Idempotency-Key: 7f3a9c2e. If the request times out and the client retries with the same key, the API must return the stored result of the first request instead of creating a second payment. The contract states the header name, whether it is required, and how long the key is stored. Without that, a retry after a timeout becomes a duplicate payment, and the customer is debited twice. Idempotency is not a feature the developer adds later; it is part of the contract from the start. For a business analyst, writing an OpenAPI contract is a requirements exercise, not a coding exercise. The BA starts from the business need, for example a corporate client must be able to initiate a payment and check its status. The BA then defines the fields the client must send, the fields the API must return, the validation rules, the error cases, and the security. The BA reviews the contract with the developer, the tester and the security team, and signs it off before any code is written. The contract is then versioned, because a change to a required field or a response format is a breaking change that affects every client. A good contract is clear, complete, and stable, and it is the difference between an API that works and an API that generates support tickets.