ISO 20022 APIs

ISO 20022 began as a messaging standard for payment instructions, with well known messages such as pain zero zero one for customer credit transfers and pacs zero zero eight for interbank transfers. The standard has grown beyond messages into APIs, because banks and corporates wanted the same rich data model in real time interfaces as they already had in files and SWIFT messages. ISO 20022 APIs define standard resources and operations for payment initiation, status reporting, account information and cash management, using the same business concepts and the same data dictionary as the messages. A payment initiated through an ISO 20022 API therefore carries the same structured remittance information and the same party details as a payment initiated through a file. The advantage of a standard API is interoperability. A corporate that works with ten banks does not want to learn ten different API designs, ten different field names for the same concept, and ten different error formats. If all ten banks expose ISO 20022 APIs, the corporate can build one integration and reuse it, changing only the connection details. This is the same logic that made SWIFT messages successful, applied to the API world. Standards bodies and industry groups, such as the Berlin Group in Europe and the UK Open Banking Implementation Entity, have published ISO 20022 based API specifications that banks implement, and regulators in some markets have made them mandatory for open banking. Adoption is still uneven, and a BA should be realistic about that. Many banks expose ISO 20022 APIs for some products and proprietary APIs for others, and the mapping between the API model and the bank's internal systems is often where the real work lies. The internal payment hub may store data in its own format, so the API layer must translate between the ISO model and the internal model in both directions, and that translation must be tested thoroughly. Requirements in this area cover the mapping table, the handling of fields the internal system does not support, and the behaviour when a field is mandatory in the standard but optional internally. A BA who understands both the standard and the bank's systems is the bridge between them. A worked example shows an ISO 20022 API in action. A bank exposes its payment initiation API using ISO 20022 message structures carried as JSON. The client sends a pain.001 equivalent: a JSON object with a group header, a payment information block, and a credit transfer transaction block, each field named after the ISO 20022 element it represents. The bank validates the request against the ISO 20022 schema, converts it to a pacs.008 for clearing, and returns a pain.002 equivalent with the status ACCP. The benefit is that the client and the bank use the same field names, the same code sets, and the same validation rules as the clearing system, so there is no translation loss between the API and the clearing message. A payment that is valid at the API is valid at the clearing system, because both use the same definition. For a business analyst, the requirement is to define the mapping between the API JSON fields and the ISO 20022 elements, and to test that a payment accepted by the API is accepted by the clearing system. A failure scenario tests the mapping. A client sends a payment with a remittance information field of 200 characters, but the ISO 20022 pacs.008 field for unstructured remittance information allows a maximum of 140 characters. The API must reject the request with a 422 error and a message stating the field exceeds the maximum length, rather than truncating the field silently and sending a payment with incomplete remittance information. Truncation is a data loss defect: the beneficiary receives a payment with a remittance reference that does not match the invoice, and the reconciliation fails. The API must validate against the ISO 20022 limits, not just against its own JSON schema, because the clearing system will reject a message that exceeds them. Last reviewed 7 November 2026. Further reading: ISO 20022 pain.001, pacs.008 and pain.002 message definitions; ISO 20022 message usage guidelines. Take a pain.001 file that a corporate has used for years, and the same payment initiated through an ISO 20022 API. The file has a group header, a payment information block, and a credit transfer transaction with the debtor, the creditor, the amount and the remittance information. The API call has the same data, expressed as JSON: a payment resource with the debtor and creditor as nested objects, the amount as a structured value, and the remittance information as a field. The bank's API layer translates the JSON into the same internal canonical model that the file gateway produces, so both paths are processed identically downstream. The BA's mapping table must show each pain.001 field, its JSON equivalent, and what happens when a field is mandatory in one format and optional in the other. Field mismatches are the most common ISO 20022 API failure. Suppose the corporate sends a structured address with a street name and a building number, but the bank's internal system only stores an unstructured address as free text. The API layer must either concatenate the structured fields into one line, which loses precision, or reject the payment, which breaks the integration. The right answer is usually to store both, structured for the standard and unstructured for the legacy system, and to test the conversion with addresses from every country the bank serves. A BA should specify the address handling rule for each field, because addresses are where most mapping errors hide. Standardisation is a business decision, not just a technical one. A bank that adopts ISO 20022 APIs can serve corporates who work with ten banks through one integration, which is a selling point. But the bank must also maintain its proprietary APIs for clients who built on them, and must map between the two, which is a cost. The BA should write the business case for standardisation, the migration plan for existing clients, and the test pack that proves the standard API behaves the same as the proprietary one. A standard that is adopted halfway, with some fields mapped and others ignored, is worse than no standard at all, because it creates the illusion of interoperability.