From Files and SWIFT to Real Time APIs

For most of banking history, payments moved through files and messages that were exchanged in batches. A corporate customer would send a file of payments at the end of the day, the bank would process it overnight, and the customer would get a report the next morning. SWIFT messages moved between banks in a similar store and forward way, reliable but not instant. This worked when payments were planned in advance, but it fits poorly with a world where a customer expects to pay from a phone and see the result immediately, and where a business wants to pay a supplier from inside its own accounting software without logging into a bank portal. The shift to APIs is the banking industry's answer to that expectation. An application programming interface, or API, is a defined way for one software system to ask another system to do something, and to get a structured answer back. In payments, an API lets a corporate treasury system ask a bank to initiate a payment, check an account balance, or get the status of a payment, without any human involvement and without a file transfer. The request and the response are usually in JSON format, sent over HTTPS, and the whole round trip takes seconds. This is what makes embedded finance possible, where a payment happens inside a non banking app, such as an e commerce checkout or a ride hailing app, and the customer never sees the bank at all. For a business analyst, the API shift changes the nature of the work. Instead of writing requirements for screens and files, the BA writes requirements for API resources, operations, request and response fields, error codes and status transitions. The BA must think about the developer who will consume the API, because a badly designed API is hard to use and produces support calls and integration errors. Good API requirements cover the happy path, the error paths, the limits, the security model and the test environment, because a corporate developer needs all of those to build a reliable integration. This chapter covers each of those areas in turn. A worked example shows the shift from files to APIs. A corporate customer pays 500 suppliers every Friday. In the file world, the treasury system generates a pain.001 file with 500 payment instructions, uploads it to the bank portal, and waits for the bank to process it overnight. The customer learns the result the next morning, when the bank returns a pain.002 status report. If one payment in the file is wrong, the whole file may be rejected, or the one payment may be rejected and the other 499 processed, and the customer must read the pain.002 to find out which. In the API world, the treasury system calls the bank API once per payment, receives an immediate response for each, and knows within seconds whether each payment was accepted. If one payment is wrong, only that one is rejected, and the response says why. The API is faster, more precise, and easier to reconcile, which is why corporate customers are moving to it. For a business analyst, the requirement is to define the migration path: which customers move first, how the file and API channels coexist during the transition, and when the file channel is retired. A failure scenario tests the coexistence. During the transition, a corporate customer sends the same 500 payments by file and by API, because its treasury system was misconfigured to use both channels. The bank receives 1,000 payment instructions for 500 payments. The hub must detect the duplicates: it matches the file instructions and the API instructions by end to end identification, finds that 500 are duplicates, and rejects the second copy of each with a clear reason. If the hub does not detect the duplicates, the suppliers are paid twice, and the customer must recover the duplicate payments. The defence is the end to end identification: every payment instruction, whether by file or by API, must carry a unique end to end identifier, and the hub must check it before processing. Last reviewed 7 November 2026. Further reading: ISO 20022 pain.001 and pain.002 message definitions; Berlin Group NextGenPSD2 API framework. Take a corporate treasurer who pays 500 suppliers every Friday. In the old world, the treasurer exports a file from the accounting system, uploads it to the bank portal, waits for the bank to process it overnight, and downloads a report on Monday. In the API world, the accounting system calls the bank's payment initiation API 500 times, each call returns a payment reference and a status within seconds, and the treasurer sees the results in the accounting system the same day. The difference is not just speed, it is that the payment is now part of the treasurer's own workflow, not a separate task in a separate system. That is why corporates adopt APIs, and why banks that offer only files lose corporate business. When an API is down, the corporate cannot pay, and the failure is visible immediately. Suppose the bank's API gateway returns errors for 20 minutes on a Friday afternoon, and 200 payment requests fail. The corporate system must know which payments were created and which were not, so it retries only the failed ones, using idempotency keys to avoid duplicates. The bank must publish a status page, notify affected clients, and provide a fallback, usually a file upload, for urgent payments. A BA should write the outage requirement as a service level: the API must be available 99.9 percent of the time, must respond within 2 seconds for 95 percent of calls, and must tell the client within 5 minutes when it is degraded. API requirements are different from screen requirements, and the BA must write them differently. Instead of screens and fields, the BA writes resources, operations, request and response bodies, error codes and status transitions. Each endpoint needs a purpose, a version, an authentication method, a rate limit, and a test environment. The BA should also define the developer journey: how a corporate signs up, gets credentials, tests in the sandbox, and goes live. A bank that makes onboarding hard will have an API nobody uses, however good the technology is.