API Business Data, Rules and Validations

The payment initiation API is the front door to the new ISO 20022 world, and it accepts payment instructions from channels such as internet banking, mobile banking and the corporate file upload service. The API receives a structured request with the debtor account, the creditor name and account, the amount, the currency, the value date, the remittance information and an end-to-end identification supplied by the channel. The API's job is to validate the request, convert it into a pacs.008 message, and return a clear result to the caller, all within a response time of under two seconds. Field validations run in a fixed order so that the first error reported is the most useful one. The API first checks that all mandatory fields are present, then checks the format of each field, then checks the business rules. Format checks include verifying that the IBAN is exactly 34 characters for a German beneficiary and passes the modulus 97 check, that the amount is a positive number with no more than two decimal places, and that the currency is a valid ISO code such as USD, EUR or GBP. A request that fails a format check is rejected immediately with the field name and the reason. Business rule validations come next and they depend on the customer and the product. The API checks that the debtor account has sufficient balance for the amount plus the charge, that the amount is within the customer's daily limit, which might be 1,000,000 rupees for a retail customer and 50,000,000 rupees for a corporate customer, and that the value date is not in the past and not more than 30 days in the future. It also checks that the purpose code, where required, is one of the approved values for that corridor. Each failed rule returns a specific error code so the channel can show the customer a message that explains what to fix. Error handling must distinguish between errors the customer can fix and errors the system must handle. A validation failure returns an HTTP 400 response with a structured error body naming the field and the code, for example code 4002 with the message amount exceeds daily limit. A downstream failure, such as the payment hub being unavailable, returns an HTTP 503 with a retry instruction. The API never returns a bare error or a stack trace, because the channel cannot display it and the customer cannot act on it. Every error is also logged with the request identification so operations can trace it. Idempotency is the rule that sending the same request twice must not create two payments, and it is one of the most important requirements in the API. The channel sends an idempotency key, which is a unique value such as a UUID, in the request header. The API stores the key with the result of the first request, and if the same key arrives again within 24 hours, the API returns the original result instead of processing the payment again. This protects against the common case where a customer double-clicks submit, or a network timeout causes the channel to retry a request that actually succeeded. Duplicate detection is the second line of defence and it works on the business data rather than the key. The API checks whether an identical payment, meaning the same debtor account, creditor account, amount, currency and value date, was already submitted in the last 24 hours. If a match is found, the API returns a warning with the original payment identification and asks the channel to confirm whether the customer really wants to send a second identical payment. A customer paying a supplier 250,000 rupees twice in one day is plausible, but it is unusual enough to warrant a confirmation step.