# Payment API Integration Let corporate treasury systems initiate payments directly, safely and in real time This project builds a payment initiation API for the corporate banking channel, so that treasury teams can send payments from their own systems instead of typing each instruction into internet banking. A corporate customer submits a payment of 25,000 dollars to a supplier in New York, a payment of 100,000 euros to a supplier in Frankfurt, and a bulk file of 200 salary payments, all through the same API, and receives a real time response with the payment status. The business analyst defines the business problem, writes the requirements for initiation, validation, approval, screening and status reporting, designs the idempotency and error handling rules, and specifies the API contract that corporate customers build against. The project covers OAuth 2.0 authentication, daily limits, approval workflows, webhook notifications, sandbox testing and a controlled production launch with the first corporate customers. ## Phases ### Discovery and Business Case - Document current corporate payment processes and pain points - Interview corporate customers, channel and operations teams - Define API objectives, target customers and measurable benefits - Agree scope, payment types, currencies and launch customers ### Requirements and API Design - Write business requirements for initiation, status and cancellation - Design endpoints, schemas, error codes and idempotency rules - Define limits, approval workflows and cutoff rules - Agree non functional requirements for security and performance ### Architecture and Integration Design - Define API gateway, orchestration and hub components - Design integrations with screening, core banking and clearing - Specify authentication, authorisation and rate limiting - Agree data model, logging, audit and resilience design ### Build Support - Support developers during API and orchestration build - Create sandbox test data for corporate integration teams - Support API testing with the first corporate customers - Track defects and update requirements where needed ### Testing and Certification - Create UAT scenarios for standard, duplicate and timeout cases - Support performance, security and penetration testing - Run certification with clearing systems and corporate partners - Obtain business sign off for each release ### Launch and Hypercare - Plan phased launch by corporate customer and payment type - Prepare integration guides, runbooks and support training - Monitor API success rates and response times in hypercare - Hand over to operations and close the project ## Deliverables ### BRD The Business Requirements Document states what the business needs from a payment initiation API for the corporate banking channel, including the payment types, currencies, channels and customer segments in scope. It covers single and bulk payment initiation, payment status enquiry, cancellation and webhook notifications, and it defines the business rules for limits, cutoffs, approval workflows, charges and exception handling. It is signed off by business, operations, compliance and technology before design starts. Template sections: - Executive Summary - Business Objectives and Scope - Payment Types, Channels and Customers - Current State and Pain Points - Target State API Capabilities - Business Rules and Controls - Stakeholders and RACI - Risks, Assumptions and Sign Off ### FSD The Functional Specification Document describes how the payment initiation API must behave at each step, from request receipt and authentication through validation, limit checks, screening, routing and status reporting. It defines the rules for idempotency, duplicate prevention, timeout handling, retries and error reporting, and it states the behaviour for approvals, rejections and cancellations. Developers and testers use it as the precise specification for build and test. Template sections: - Introduction and Scope - System Context and Interfaces - Request Lifecycle and State Model - Validation, Limits and Approval Rules - Idempotency and Duplicate Handling - Error Handling and Status Reporting - Non Functional Requirements - Appendices and Reference Data ### Process Flow The Process Flow shows the end to end journey of a payment initiated through the API, from the corporate treasury system to beneficiary credit, with swimlanes for the customer, the API gateway, the payment hub, compliance and the clearing system. It shows decision points for authentication, validation, approval, screening and routing, and the exception paths for rejection, timeout and duplicate detection. Operations and integration teams use it to understand the new process and to train staff. Template sections: - Process Overview and Scope - Actors and Swimlanes - Initiation and Authentication Flow - Validation and Approval Flow - Screening, Routing and Settlement Flow - Exception and Duplicate Paths - Controls and Handoffs - Timing and Cutoffs ### Solution Architecture The Solution Architecture describes the technology design for the payment API, including the API gateway, the authentication service, the payment orchestration service, the payment hub, the screening platform and the core banking system. It shows how requests flow between systems, where idempotency keys and correlation IDs are stored, how resilience and failover work, and how the design meets security, performance and audit requirements. It guides developers and infrastructure teams during build and deployment. Template sections: - Architecture Overview - System Landscape and Components - Message Flow and Integration Pattern - Data Architecture and Storage - Security and Access Control - Resilience, Performance and Scalability - Deployment and Environments - Risks and Design Decisions ### Data Mapping Sheet The Data Mapping Sheet lists every field that flows through the API, from the corporate request payload to the payment hub record, the clearing message and the ledger entry. It shows the source, the target, the data type, the transformation rule and the validation rule for each field, including party, account, amount, currency, value date, remittance information and charges. It is the reference that developers and testers use to build and verify every interface. Template sections: - Mapping Overview and Conventions - API Request to Hub Field Mapping - Hub to Clearing Mapping - Hub to Core Banking Mapping - Hub to Ledger Mapping - Validation Rules per Field - Transformation and Default Rules - Version History ### API Specification The API Specification defines the interfaces for payment initiation, payment status, payment cancellation, bulk file submission and webhook notifications. It lists each endpoint, the request and response payloads, the authentication method using OAuth 2.0, the error codes, the idempotency key handling, the correlation ID rules and the service levels for response time and availability. It lets corporate customers and channel teams integrate with the bank safely and consistently. Template sections: - API Overview and Principles - Authentication and Authorisation - Endpoint Catalogue - Request and Response Payloads - Error Codes and Handling - Idempotency and Duplicate Prevention - Performance and Rate Limits - Versioning and Change Control ### Jira User Stories Jira User Stories break the API build into small, deliverable pieces that a development team can complete in a sprint. Each story states the user need, the business value and the acceptance criteria, and it is linked to the BRD, the FSD and the data mapping sheet. Stories cover authentication, initiation, validation, approval, screening, status reporting, cancellation and webhooks, with clear priorities, dependencies and a definition of done. Template sections: - Epic and Story Structure - Story: Authentication and Authorisation - Story: Payment Initiation - Story: Validation and Approval - Story: Status Reporting and Webhooks - Story: Cancellation and Error Handling - Story: Bulk Submission - Definition of Done ### Acceptance Criteria Acceptance Criteria define the conditions that must be met before an API feature or release is accepted by the business. Each criterion is specific, measurable and testable, and it states the expected result for a given request, including authentication, validation, approval, idempotency, status reporting and error handling. Criteria are agreed before development starts and are used as the basis for user acceptance testing, performance testing and production sign off. Template sections: - Acceptance Criteria Principles - Criteria per User Story - Authentication and Validation Criteria - Idempotency and Duplicate Criteria - Status and Webhook Criteria - Performance Criteria - Security and Audit Criteria - Sign Off Checklist ### UAT Scenarios UAT Scenarios describe the business tests that prove the API works end to end, from a 25,000 dollar payment initiated by a corporate treasury system to a 100,000 euro bulk file and a cancelled payment. Each scenario states the precondition, the test steps, the input request, the expected output and the evidence required. Scenarios cover a standard single payment, a payment above the approval threshold, a duplicate submission, an invalid IBAN, a timeout, a cancellation and a webhook delivery, so the business can sign off with confidence. Template sections: - UAT Scope and Approach - Test Environment and Data - Scenario: Standard Single Payment - Scenario: Approval and Bulk File - Scenario: Duplicate and Timeout - Scenario: Invalid Data and Rejection - Scenario: Cancellation and Webhook - Defect Management and Sign Off ### RTM The Requirements Traceability Matrix links every API requirement in the BRD to its functional specification, its design component, its user story, its test case and its UAT result. It shows which requirements are covered, which are in progress and which have failed testing, so that no requirement is lost during the build. It is the main evidence that the API meets the agreed scope and is ready for production release. Template sections: - Traceability Principles - BRD to FSD Mapping - FSD to User Story Mapping - User Story to Test Case Mapping - Test Case to UAT Result Mapping - Coverage Summary - Open Items and Gaps - Sign Off