ADR-032: Customer notification service — Amazon Pinpoint¶
| Status | Accepted |
| Date | 2026-04-10 |
| Deciders | CTO, Head of Architecture |
| Affects repos | bank-kyc, bank-payments, bank-app, bank-core |
Status¶
Accepted — 2026-04-10
Context¶
The platform requires customer notifications across multiple channels: SMS OTP during onboarding and step-up auth (ADR-026), transaction alerts, regulatory disclosures, and push notifications to the mobile app. CON-004 (product disclosure) and AML-008 require evidence of delivery for compliance purposes. No notification service was specified in prior ADRs.
Decision¶
Amazon Pinpoint (ap-southeast-2) is the customer notification service for all channels.
| Channel | Use cases |
|---|---|
| SMS | OTP delivery (onboarding, step-up auth), fraud alerts, account status notifications |
| Regulatory disclosures, statements, terms changes, account confirmations | |
| Push | Transaction notifications, insight cards, action-required alerts (APNs for iOS, FCM for Android) |
Delivery receipts: All delivery events (sent, delivered, failed, bounced) are exported from Pinpoint event streams to S3 via Kinesis Firehose for long-term retention — satisfying CON-004 and PRI-003 retention requirements without custom logging code.
Template governance: All notification templates are version-controlled in Pinpoint. Regulatory disclosure templates (fee changes, terms updates) require compliance sign-off before activation — enforced via the release pipeline, not ad hoc sends.
Journey orchestration: Multi-step flows (OTP retry logic, onboarding nudges) are implemented as Pinpoint journeys rather than custom Lambda state machines.
Sending pattern: Lambda functions invoke Pinpoint via the AWS SDK. All sends route through Pinpoint — no Lambda sends directly to SMS or email providers — so delivery is logged centrally regardless of which domain triggers the notification.
Rejected alternatives¶
| Option | Reason rejected |
|---|---|
| Amazon SES + SNS separately | No unified delivery log; no push channel; no journey orchestration; three services to operate |
| Twilio / SendGrid | Routes through US infrastructure by default — data residency complexity; third-party dependency outside AWS boundary |
| Custom Lambda + SES | No delivery tracking, no template versioning, no retry management |
Consequences¶
Single service handles all outbound customer communication. Delivery evidence retained automatically — compliance requirement met without custom logging. Data residency consistent with ADR-023 (Sydney). Pinpoint marketing campaign features are not used — transactional and regulatory sends only.
Signoff record¶
| Date | Name | Role | Status |
|---|---|---|---|
| 2026-04-10 | Ross Millen | CTO | Approved |
| 2026-04-10 | Ross Millen | Head of Architecture | Approved |
| 2026-04-10 | Ross Millen | Head of Data | Approved |
Capabilities¶
| Capability | Description | Relationship |
|---|---|---|
| CAP-021 | Low balance alert | enabled — Pinpoint delivers the low balance push/SMS alert |
| CAP-022 | Unusual transaction alert | enabled — fraud and anomaly alerts delivered via Pinpoint |
| CAP-036 | Passkey / FIDO2 authentication | enabled — SMS OTP for onboarding and step-up auth delivered via Pinpoint |
| CAP-058 | Notification preferences (granular) | governed — Pinpoint supports per-channel preference management |
| CAP-103 | Notification triggering | enabled — Pinpoint is the service that executes all notification sends |
| CAP-104 | Channel selection & preference | enabled — Pinpoint handles SMS, email, and push from a single service |
| CAP-105 | Communication audit trail | enabled — delivery receipts exported to S3 for long-term retention |
Related decisions¶
| ADR | Title | Relationship |
|---|---|---|
| ADR-023 | Cloud provider and region strategy | Pinpoint in ap-southeast-2 satisfies data residency |
| ADR-026 | Customer authentication — Cognito, mobile-first, passwordless | SMS OTP delivery uses Pinpoint |
All ADRs
Compiled 2026-05-22 from source/entities/adrs/ADR-032.yaml