Writing a Use-Case Document for System-Triggered Payments

A use-case document starts with the basic identification fields, and these matter more than people think. The document needs a unique identifier such as UC-014, a clear name such as Process Subscription Renewal Payment, the actor or actors involved, and the trigger that starts the flow. For a system-triggered payment, the primary actor is often the billing system itself, with the customer and the payment gateway as secondary actors. The document also states the preconditions, which describe what must be true before the flow starts, and the postconditions, which describe what must be true when it ends. Without clear preconditions, developers cannot tell when the flow should run at all. The preconditions for a subscription renewal payment are specific and testable. The subscription must be in active status, the next billing date must be today, the customer must have a valid stored payment credential, and the mandate must not be cancelled or suspended. The system must also have a calculated order amount, including the subscription discount and any delivery charges. If any precondition fails, the flow should not start, and the system should log the reason. A business analyst writes these as a numbered list so that testers can verify each one, and so that developers can code the checks in the right order. The main flow, sometimes called the happy path, describes the steps when everything works. First, the billing engine selects all subscriptions due for renewal. Second, it calculates the amount for each subscription. Third, it sends a 3RI authentication request to the gateway using the stored credential. Fourth, it submits the authorisation request with the authentication value. Fifth, it receives an approval, captures the payment, and generates the order. Sixth, it sends a confirmation message to the customer and updates the next billing date. Each step names the system that performs it, the data it needs, and the result it produces, so that there is no ambiguity about responsibility. Alternate flows describe the valid variations of the main flow, and exceptions describe what happens when things go wrong. An alternate flow covers a partial fulfilment, where one product is out of stock and the order proceeds with the rest. Another alternate flow covers a price change, where the system charges the new price and tells the customer. Exceptions include a declined authorisation, a gateway timeout, and an expired card. For each exception, the document states the system response, the customer notification, and the retry rule. A use case without alternate flows and exceptions is only a description of the easy day, and the easy day is not what breaks in production. Here is a worked example in brief, using the Subscribe n Save renewal. The use case is UC-014, Process Subscription Renewal Payment. The actor is the billing engine, and the trigger is the scheduled job running at 2 in the morning. The preconditions are an active subscription, a billing date of today, and a valid token. The main flow runs through authentication, authorisation, capture, order creation, and confirmation. The first exception is a declined authorisation, which triggers a retry after 24 hours and a message to the customer. The second exception is an expired card, which suspends the subscription and asks the customer to update the card. This example fits on two pages, and it gives developers and testers everything they need.