External provider stub service¶


ID	`MOD-157`
System	SD07
Repo	`bank-platform`
Build status	Deployed
Deployed	Yes
Last commit	`dde93477171584efcf1087c37da133bf846c4c06`

Purpose¶

MOD-157 provides Lambda stub functions for every external third-party provider used across the platform's eight system domains — identity verification, payment clearing networks, credit bureaus, and open banking connectors. It also deploys notification capture infrastructure for Amazon Pinpoint and a rules-based fraud model stub for MOD-023.

Without this module, integration tests for modules that call external APIs would either call real production endpoints (unsafe, expensive, non-deterministic) or require each module to implement its own mocking strategy (inconsistent and incomplete).

The compliance reason is DT-007: every module must pass integration tests against the dev environment before it is eligible for UAT promotion. Those integration tests cannot pass without realistic provider responses. MOD-157 makes that possible without regulatory exposure.

Architecture¶

consuming module Lambda
  │
  ├── reads SSM: /{repo}/{stage}/provider/base-url
  │                       │
  │              dev/UAT: └──► MOD-157 API Gateway
  │                              └── stub Lambda handler
  │                                    └── DynamoDB (stub state)
  │                                    └── async: fires webhook callback
  │
  └── prod: real provider URL from SSM

One API Gateway serves all stubs in a given stage. Routes are namespaced by provider category: - /oidv/* — eIDV providers (DVS, DIA, Onfido, Equifax, Centrix) - /sanctions/* — sanctions and PEP list downloads (MOD-013, MOD-014) - /clearing/npp/* — NPP real-time payments (AU) - /clearing/becs/* — BECS direct debit batch (AU) - /clearing/swift/* — SWIFT cross-border messages - /clearing/bpay/* — BPAY bill payments (AU) - /clearing/esas/* — ESAS real-time gross settlement (NZ) - /clearing/nzfp/* — NZ faster payments - /openbanking/akahu/* — Akahu open banking (NZ) - /openbanking/cdr/* — CDR open banking (AU) - /bureau/* — credit bureau enquiries (Equifax AU, Centrix NZ) - /post-sftp/* — Australia/NZ Post agency banking batch simulation - /notifications/capture — notification log query endpoint

SSM outputs¶

MOD-157 writes stub endpoint URLs to SSM at the paths each consuming module reads. The pattern is:

/{repo}/{stage}/{provider-category}/base-url  →  https://stubs.{stage}.{domain}/{category}

Consuming modules declare their expected SSM paths in their own docs/design/MOD-NNN.md. The reusable-iac.yml step verifies these paths exist after MOD-157 is deployed.

Test pattern convention¶

Stub responses are driven by patterns in request input data, not by configuration switches. This makes integration tests self-contained:

Provider	Test pattern	Response
eIDV (all)	Document ref `PASS-*`	Verified, high confidence
eIDV (all)	Document ref `FAIL-*`	Rejected — identity mismatch
eIDV (all)	Document ref `REFER-*`	Manual review required
Onfido	Webhook fires	2 seconds after initial request
Sanctions	Name contains `SANCTIONED`	Confirmed match
Sanctions	Name contains `PEP-`	PEP hit, no sanctions
NPP	Destination account ends `0001`	Cleared, settlement confirmed
NPP	Destination account ends `0002`	Dishonoured — insufficient funds
NPP	Destination account ends `0003`	Timeout — no clearing response
BECS	Payer BSB `062-000`	All presentments honour
BECS	Payer BSB `062-001`	Second presentment dishonours
Bureau	Date of birth `1900-01-01`	No bureau record found
Bureau	Date of birth `1900-01-02`	Adverse record present

Async stub behaviour¶

For providers with async clearing lifecycles (Onfido, NPP, BECS, SWIFT, ESAS), the stub stores the pending request in DynamoDB and fires a webhook callback to the consuming module's registered callback URL after a configurable delay (default 2 seconds). The callback URL is read from SSM at /{repo}/{stage}/{provider}/callback-url, written by the consuming module at its own deploy time.

Notification capture¶

Amazon Pinpoint is used as a real AWS service in all environments. A notification capture Lambda is subscribed to the SNS topic that MOD-063 uses for dispatched messages. Every notification (type, recipient address, subject, body, timestamp) is written to a DynamoDB table notification-capture-{stage}. Integration tests query this table via the /notifications/capture endpoint to assert delivery.

Query pattern:

GET /notifications/capture?customer_id=CUST-001&type=email&after=2026-04-27T00:00:00Z

Fraud model stub¶

The fraud model artefact path is configured via SSM at /bank-payments/{stage}/fraud/model-s3-path. In dev and UAT, this path points to a stub model file deployed by MOD-157. The stub applies simple rules:

Amount > NZD/AUD 10,000 → score 0.9 (auto-decline threshold)
Payment reference contains FRAUD-TEST → score 0.9
All other payments → score 0.1 (pass)

MOD-023 code and configuration are unchanged; only the model artefact differs between environments.

Deployment scope¶

MOD-157 is deployed to dev and uat stages only. The sst.config.ts for this module conditionally skips all resource provisioning when stage === 'prod'. Running sst deploy --stage prod on this module is a no-op.

Module dependencies¶

Depends on¶

Module	Title	Required?	Contract	Reason
MOD-104	AWS shared infrastructure bootstrap	Required	—	AWS account, OIDC federation, and base IAM roles must exist before the stub API Gateway and Lambda functions can be deployed.
MOD-076	Observability platform	Required	—	ADOT observability layer ARN is read from SSM at deploy time and attached to all stub Lambda functions.
MOD-045	Secrets & key management	Required	—	Secrets Manager is used to store any provider-category API keys needed by the notification capture path; MOD-045 must exist before MOD-157 can write secrets.

Required by¶

Module	Title	As	Contract
MOD-114	Direct debit mandate management	Hard dependency	—
MOD-136	BPAY biller registration and inbound BPAY	Hard dependency	—
MOD-158	Test seed data loader	Hard dependency	—
MOD-160	Cross-module acceptance suite	Hard dependency	—

Policies satisfied¶

(No policies assigned)

Capabilities satisfied¶

(No capabilities mapped)

Part of SD07 — Data Platform & Governance Infrastructure Compiled 2026-05-22 from source/entities/modules/MOD-157.yaml