API Analysis and Interface Specifications

An application programming interface, or API, is how one system asks another system to do something, and in payments the most common API is the payment initiation API, which lets a channel such as internet banking ask the payment hub to send a payment. The interface specification is the contract between the two systems, and the business analyst reads it to confirm that it covers every field, every validation and every error the business needs. A specification that looks complete to a developer can still be missing a business rule, and that gap is the analyst's job to find. The request is the message the calling system sends, and the analyst checks each field in it. A payment initiation request typically carries a debtor account number, a creditor name, a creditor account number or IBAN, an amount, a currency, a value date, a remittance reference, and an end-to-end identification that tracks the payment through the whole chain. The analyst checks that every mandatory business field has a matching request field, that the field lengths match the downstream message format, and that optional fields such as the purpose code are present where compliance requires them. The response is the message the API sends back, and it must tell the caller exactly what happened. A successful response returns a payment status such as Accepted, a unique payment identification, and the time the payment was accepted. A rejected response returns an error code and a human readable message. The analyst checks that the response covers all the states the business needs, including Accepted, Rejected, Pending and Queued, because a channel that cannot tell a customer why a payment is pending will generate calls to the contact centre. Error codes are where interface specifications most often fall short. A good specification defines a code for each failure. For example, 4001 for an invalid account number, 4002 for an amount above the permitted limit, 4003 for a missing mandatory field, and 5001 for a downstream system timeout. Each code needs a description, the condition that triggers it, and the action the caller should take, such as asking the customer to correct the input or retrying later. The analyst also checks that errors are returned in a consistent format, so the channel can display them reliably. The analyst also checks the non-functional parts of the specification, which are easy to overlook. These include the maximum number of requests per second the API will accept, the timeout after which the caller should treat the request as failed, the authentication method, and whether the API is idempotent, meaning that sending the same request twice does not create two payments. Idempotency is critical in payments. If a customer clicks submit twice, or a network retry resends the request, the system must recognise the duplicate and return the original result instead of debiting the account twice. A practical check the analyst performs is a field-by-field trace from the channel to the final payment message. Take a payment of 75,000 rupees from a savings account to a supplier's account. The analyst follows the debtor account from the API request, through the payment hub, into the core banking debit, and out to the clearing message, confirming that the account number, amount and currency are carried correctly at every step. Any field that is transformed, truncated or dropped along the way is flagged as a defect in the interface document before development starts.