Payment initiation¶


ID	`MOD-071`
System	SD08
Repo	`bank-app`
Build status	Deployed
Deployed	Yes
Last commit	`c98d4214fd3e613d6a3c873f68551d129ff1a485`

Payment initiation is the customer-facing entry point for all outgoing payment types: domestic transfers, international wires, BPAY, scheduled payments, and direct debit management. It presents a consistent initiation experience across payment types while routing each submission to the appropriate backend processing module.

Two-step flow (PAY-001)¶

All payments follow a preview→confirm two-step sequence. POST /payments/preview assembles a ValidatePaymentRequest payload, calls MOD-050 for any required FX disclosure, evaluates step-up requirements, and returns a preview_id with the full fee and FX breakdown. POST /payments/confirm accepts the preview_id plus an optional step_up_token; it will not proceed without a valid preview_id (422 if missing or expired). Direct submission paths are rejected. A negative test asserts that confirm-without-preview returns 422.

app.payment_previews rows expire after 15 minutes. The preview_id is the public reference throughout the flow.

FX and fee transparency (CON-005)¶

The preview response always carries fee_amount, fx_rate, fx_markup, base_currency_amount, and total_to_debit. The confirmation screen surfaces all of these before the customer taps confirm. For FX payments (INTERNATIONAL_WIRE), MOD-050 is called at preview time for a FX_TERMS_AND_CONDITIONS disclosure acknowledgement gate. If MOD-050 returns "not required" (disclosure type not yet catalogued), the flow proceeds — this is the v1 posture; the disclosure type will be added in a follow-up MOD-050 amendment.

Step-up authentication (FR-355)¶

Step-up is required for two conditions: (a) payment amount exceeds the configured threshold (default NZD/AUD 500, env-var STEP_UP_THRESHOLD_DEFAULT; customer-configurable deferred to v1.1); (b) the matched payee in app.payees has first_use_completed = false. When either condition applies, step_up_required = true is returned on the preview response. The confirm handler invokes MOD-068 via Lambda invoke (STEP_UP_FN_ARN injected from SSM path /bank/{env}/mod068/step-up/fn-arn) to verify the x-step-up-token header. first_use_completed is set to true on the payee row after a successful first payment.

Payment submission¶

On confirm: MOD-071 calls POST /internal/v1/payments/validate on MOD-020 synchronously, passing the pre-minted payment_id (minted at preview creation — same pattern as MOD-141/MOD-119/MOD-120/MOD-122) and the idempotency_key derived as sha256(preview_id::text || ':' || party_id::text). MOD-020 creates the canonical payments.payments row with the pre-minted payment_id. SigV4 signing uses BankAppRole. If MOD-020's resource policy has not yet been extended to BankAppRole, a handoff is filed to bank-platform — same file-if-needed approach as MOD-070. MOD-071 does not publish any EventBridge events; MOD-020 publishes bank.payments.payment_initiated as the canonical payment signal.

Scheduled payments¶

app.scheduled_payments stores one-off and recurring payment instructions. The scheduled-payment-sweeper Lambda runs daily at 07:00 NZST (cron(0 19 ? * * *)). For each ACTIVE row with next_run_at <= now(), the sweeper mints a fresh payment_id, derives a per-run idempotency key (idempotency_prefix || ':' || run_count), calls MOD-020, writes a RESULTED event (carrying MOD-020's decision), and updates next_run_at (recurring) or sets status = 'COMPLETED' (one-off). OSKO is excluded from scheduled payments — it is a real-time rail not suited to future-dating.

Direct debit management (CAP-009)¶

v1: GET /direct-debits returns [] with a deferral note. DD mandate management is owned by MOD-114 (bank-payments). The live mandate feed will be wired in v2.

Data model¶

Four tables in the app schema. Full schemas in SD08 data model. Key points:

app.payment_previews — mutable, 15-min TTL; one row per initiation session; holds the pre-minted payment_id and full disclosure fields
app.payment_initiation_events — Cat 1 immutable (INSERT only); one row per state transition; carries session_id, device_fingerprint, mod_020_payment_id, mod_020_decision, trace_id
app.payees — mutable address book; soft-deleted; first_use_completed drives FR-355 gate
app.scheduled_payments — mutable instruction store; next_run_at index for sweeper

Module dependencies¶

Depends on¶

Module	Title	Required?	Contract	Reason
MOD-020	Pre-payment validation suite	Required	—	Payment submissions from the initiation UI are routed through the pre-payment validation suite before execution.
MOD-068	Authentication & session management	Required	—	Payment authorisation requires an authenticated session and step-up re-authentication for high-value transfers.
MOD-050	Disclosure enforcement module	Required	—	FX and fee disclosure must be acknowledged by the customer before payment confirmation is accepted.
MOD-104	AWS shared infrastructure bootstrap	Required	—	AWS shared infrastructure provisioned by MOD-104 (EventBridge buses, S3, KMS, Kinesis, Cognito) is required before this module can be deployed.
MOD-103	Neon database platform bootstrap	Required	—	Neon database and schema provisioned by MOD-103 must exist before this module can read or write Postgres.

Required by¶

(No modules in this wiki currently declare a dependency on this module.)

Policies satisfied¶

Policy	Title	Mode	How
PAY-001	Payment Operations Policy	`GATE`	Presents the full payment details for customer confirmation before submission — no payment is initiated without explicit customer authorisation.
CON-005	Fee & Pricing Transparency Policy	`AUTO`	Displays the applicable FX rate, markup, and fee clearly on the confirmation screen before the customer commits to a payment.

Capabilities satisfied¶

Capability	Title	Mode	How
CAP-004	Instant NZ transfers (NPP / PayID equivalent)	`AUTO`	Provides the UI for initiating instant NZ transfers via account number or registered payee, routing through the payment backend on confirmation.
CAP-005	International wire transfers (SWIFT)	`AUTO`	Guides the customer through SWIFT wire transfer entry including BIC, IBAN/account, and currency, with a fee and FX preview before confirmation.
CAP-007	Scheduled & recurring payments	`AUTO`	Allows customers to schedule a future-dated or recurring payment from the same initiation flow, storing the instruction in the payment scheduler.
CAP-008	Bill payments & BPAY (AU)	`AUTO`	Presents the BPAY biller search and reference entry UI, validating the biller code before submission.
CAP-009	Direct debit management	`AUTO`	Lists active direct debit mandates with the ability to pause, cancel, or view the originating merchant.
CAP-114	Payee management & address book	`AUTO`	Maintains the customer's payee address book — add, edit, delete payees — and surfaces saved payees at the top of the payment initiation flow.

Part of SD08 — Customer App & Back Office Platform Compiled 2026-05-22 from source/entities/modules/MOD-071.yaml