How BAs Write Gateway Integration Requirements

The work starts with a clear business objective and scope, written before any technical detail. For example, a mid sized electronics retailer, BrightKart, wants to accept Visa, Mastercard, RuPay and UPI on its website, with settlement in T plus 2 days and an approval rate of at least 90 percent. The scope covers checkout integration, payment page branding, tokenization for saved cards, refunds through the merchant dashboard, and webhook handling for order status updates. Out of scope are international currency settlement, in store point of sale terminals, and buy now pay later, which will be considered in a later phase. Writing the scope first prevents the project from growing during development, and gives every stakeholder the same picture of success. Functional requirements describe what the system must do, each with a unique identifier and a clear actor. Requirement GW-F-01 states that the checkout must call POST /v1/payments with order_id, amount in paise, currency INR, and the card token, and must display the gateway payment page within three seconds. Requirement GW-F-02 states that on a successful authorization, the system must store the payment_id, the authorization code and the status authorized against the order, and must not capture funds until the warehouse confirms dispatch. Requirement GW-F-03 states that a refund of up to the full captured amount must be possible from the merchant dashboard, and that the refund status must update the order to refunded within one hour of the gateway webhook. Each requirement names the input, the action and the expected output, so a developer does not have to guess. Non functional requirements cover performance, security, reliability and support, and they are often where integrations fail. Requirement GW-NF-01 states that the gateway API must respond within two seconds for 95 percent of authorization requests, measured over a rolling seven day window. Requirement GW-NF-02 states that all card data must be tokenized, that no card number or CVV is stored on BrightKart servers, and that the integration must pass a PCI DSS self assessment questionnaire before go live. Requirement GW-NF-03 states that the gateway must provide 99.9 percent uptime, a status page, and a support response within one hour for a severity one incident, such as a complete payment outage during a sale. These requirements protect the customer experience and the merchant reputation, even when the happy path works perfectly. Acceptance criteria turn each requirement into a test that can pass or fail, For GW-F-01, the criterion is that a test order for 1,999 rupees on a Visa test card returns status authorized, an authorization code and a payment_id, and the payment page loads in under three seconds. For GW-F-02, the criterion is that after the warehouse confirms dispatch, the capture call returns status captured, the order moves to paid, and the settlement report shows the same payment_id and the net amount after fees. For the refund requirement, the criterion is that a refund of 500 rupees against a 1,999 rupee order returns a refund_id, reduces the refundable balance to 1,499 rupees, and sends a webhook with event refund processed within five minutes. A requirement without acceptance criteria is only a wish, because no one can prove it is done. The analyst also documents edge cases, error handling and the go live checklist, which are easy to forget. Edge cases include a customer closing the browser during 3D Secure authentication, a webhook arriving twice, a refund requested after settlement, and a payment that authorizes but never captures. For each case, the document states the expected behavior, a duplicate webhook must be ignored, and an authorized but uncaptured payment must be voided automatically after seven days. The go live checklist covers test cards for each payment method, production API keys stored securely, webhook endpoints registered, settlement bank account verified with a one rupee test credit, and a rollback plan if approval rates fall below 85 percent in the first hour. A complete requirements document lets the merchant, the gateway and the developers agree on the same outcome before a single line of code is written.