Starling Bank Payment Integration in Payroll App

Good — here is the revised **Starling integration fixed-price spec**, tightened and now explicitly referencing:

* Your defined internal interfaces / APIs
* GitHub workflow
* Your stack and architecture constraints

You can repost this exactly.

---

# Fixed Price Project – Starling Bank Business API Integration (PHP)

## ⚠️ Fixed Price Only

This is a clearly scoped integration project.

Provide:

* Total fixed price
* Delivery timeline (weeks)
* Milestone breakdown

No hourly proposals.

---

# Project Overview

We operate a UK CIS payroll platform (PayCIS) built in:

* PHP 8+
* MySQL (relational, indexed)
* Object-Oriented architecture
* MVC-style request framework
* Strict naming conventions
* TLS-only environment
* Subdomain-based routing
* Role-based permissions

The system already:

* Calculates subcontractor net payments (CIS + VAT handled)
* Stores validated bank details
* Generates structured bulk payment lists
* Manages payment lifecycle:

* For Approval
* To Be Paid
* Paid
* Maintains full audit logging
* Uses defined internal service classes for payments

We now require **direct integration with Starling Bank Business API**.

---

# Important Architecture Note

We already have:

* A cleanly defined internal payment interface
* Clear service-layer APIs for retrieving payable batches
* Structured payment models
* Consistent database schema

The integration must plug into our existing payment service layer —
**not bypass it or rewrite core logic.**

This is an API integration project, not a system redesign.

---

# Scope of Work

## 1️⃣ Starling API Client

Build a reusable, clean OOP Starling client:

* OAuth authentication
* Secure token storage
* Automatic refresh handling
* Sandbox + live configuration
* No hardcoded credentials
* Environment-driven config

Deliverable:

* `starling_api.class.php` (or equivalent clean service class)
* Fully documented

---

## 2️⃣ Bulk Payment Submission

Using our existing internal API:

* Fetch payments marked “To Be Paid”
* Submit via Starling Faster Payments API
* Use idempotency keys
* One batch or controlled sequential processing

Each payment includes:

* Recipient name
* Account number
* Sort code
* Amount (2 decimal precision)
* Unique internal reference

Deliverable:

* Method to send payment batch
* Clean separation between:

* Data retrieval
* API payload generation
* Submission logic

---

## 3️⃣ Payment Status Handling

System must:

Store per-payment:

* Starling transaction ID
* Status (pending / completed / failed)
* Failure reason
* Timestamp

Update internal status accordingly.

Database changes allowed if necessary, but must follow our schema conventions.

---

## 4️⃣ Webhook Handling (If Supported)

* Implement secure webhook endpoint
* Signature verification
* Map webhook status → internal payment state
* Log raw webhook payload

Deliverable:

* Controller endpoint
* Webhook log table
* Replay-safe handling

---

## 5️⃣ Minimal Admin UI Additions

Add to existing admin interface:

* “Send to Starling” action
* Starling reference display
* Live payment status display
* Error feedback

No UI redesign required.

---

## 6️⃣ Logging Requirements

Create structured logs for:

* API requests
* API responses
* Webhooks
* Failures
* Initiating user

Logs must include:

* Payload
* Response
* Timestamp
* Account ID
* User ID

Must follow existing audit log conventions.

---

# Development Standards

You must adhere to:

* OOP principles
* DRY
* No deprecated PHP
* No inline SQL
* Clean separation of concerns
* Strict naming conventions
* Existing schema standards

All code must:

* Be production ready
* Include basic inline documentation
* Pass linting
* Follow consistent formatting

---

# GitHub Requirement

All development must be:

* Submitted via GitHub
* Branch-based workflow
* Pull request for review
* No direct server edits
* No ZIP file delivery

Commit history must be clean and logical.

---

# Security Requirements

* TLS only
* Encrypted token storage
* Idempotency protection
* No double-pay risk
* Strict input validation
* No credentials in frontend
* Webhook verification mandatory

---

# Out of Scope

* Multi-bank support
* Open Banking aggregation
* Refund flows
* International payments
* Credit card processing
* Accounting integrations

Starling Business API only.

---

# Deliverables

* Working Starling sandbox integration
* Production-ready live configuration
* Updated schema script (if required)
* Clean Starling API service class
* Webhook controller
* Updated admin UI integration
* Deployment instructions
* GitHub PR submission

Proposal Must Include

1. Fixed total price
2. Timeline (weeks)
3. Confirmation of:

Starling API experience
OAuth implementation
Webhook handling
Fintech or banking integrations
Examples of similar API integrations

UPDATE:

Starling developer hub access is in place, and the sandbox set up.
Our site is www.paycis.co.uk