Bank integration
Implement the bank adapter boundary: validate MEMEH instructions, execute bank-side flows, and publish authoritative lifecycle callbacks.
Adapter responsibilities
The adapter is the bank-controlled integration surface. It must be strict at the boundary and reliable in downstream execution and reporting.
| Responsibility | Expectation | Failure behavior |
|---|---|---|
| Boundary verification | Validate MEMEH signature and required headers before any processing. | Reject immediately with explicit error code; do not forward downstream. |
| Schema validation | Enforce request shape and required field rules consistently across environments. | Reject with validation errors suitable for triage (field + reason). |
| Canonical translation | Map canonical instructions into bank-side messages and internal workflows. | Fail closed; emit callback with a terminal failure when translation is not possible. |
| Execution / forwarding | Execute locally or forward to switch/rails while preserving instruction traceability. | Handle timeouts deterministically; avoid duplicate execution on retries. |
| Authoritative callbacks | Publish lifecycle updates to MEMEH for intermediate and terminal states. | Retry-safe delivery; idempotent update semantics; never “drop” terminal outcomes. |
MEMEH may retry delivery under network failure. The adapter must treat inbound instructions and callback deliveries as idempotent.
Treat signature failures, replay failures, and idempotency conflicts as security and integrity events.
Required capabilities
Minimum endpoints and behaviors required for bank participation.
Receives signed instructions from MEMEH. Must validate signature, request shape, and replay controls before processing.
Publishes authoritative status updates back to MEMEH. Must be reliable, idempotent, and retry-safe.
Security requirements
Validate signatures, timestamps, and nonces. Store secrets securely and rotate through controlled operational procedures.
Reject instructions when signature mismatches. Invalid instructions must not proceed into execution.
Enforce timestamp skew and nonce uniqueness where required. Persist observed nonces within the configured window.
Store secrets in a vault/HSM where available, restrict access by role, and rotate on schedule and on incident.
Callback model
Callbacks are the authoritative record of execution outcomes. Field rules and allowed statuses are defined in API Reference.
{
"instruction_id": "123",
"status": "approved",
"payment_status": "paid"
}| Rule | Why it exists |
|---|---|
| Reference instruction_id | Ensures unambiguous correlation to the original instruction. |
| Idempotent updates | Allows safe retries and prevents state corruption. |
| Terminal outcomes must be emitted | Prevents “hanging” instructions in client/operator views. |
| Signed callbacks (where required) | Preserves integrity across the bank↔MEMEH boundary. |
Emit callbacks as state changes occur (not only at settlement) to keep lifecycle visibility accurate.
Certification
Minimum UAT scenarios required for adapter readiness. Evidence should be reproducible and auditable.
| Scenario | Expected behavior | Evidence |
|---|---|---|
| Valid instruction (happy path) | Accept, execute/forward, and publish complete callback sequence including terminal outcome. | Logs + callback payloads + trace correlation. |
| Invalid signature | Reject at boundary; do not execute; return explicit error code. | Error response + audit event. |
| Callback validation | Callbacks reference the instruction_id and are idempotent under re-delivery. | Duplicate-delivery test results. |
| Timeout handling | Deterministic timeouts; avoid duplicate execution; publish final status when resolved. | Timeout traces + eventual outcome callbacks. |
| Adapter downtime + retries | Safe handling of retries after recovery; no double execution; callbacks resume correctly. | Recovery runbook + test replay logs. |
The adapter demonstrates correctness, reliability, and consistent callback behavior across all UAT scenarios prior to production enablement.