Bank support extension

This API adds read-only bank checks and stateless routing of reported scam observations. It does not provide another support inbox, LLM, customer directory, OTP flow or payment executor. Reuse YeboLink Customer Care/YeboAI or an existing support platform for conversations and interpretation.

All routes are server-to-server under /v1/bank-support, require the existing X-API-Key, return {success,data} and Cache-Control: no-store, and reuse authenticated business rate limits. Never distribute a bank's YeboVerify key to a browser. An integrator must map its authenticated workspace to that workspace's own YeboVerify business key, and verify customer ownership of the conversation before submitting it.

Assessment

POST /assess accepts the v1 fixture in the private API repository’s docs/contracts/bank-support-v1.examples.json. YeboLink’s Customer Care integration supplies observations from its existing YeboAI path; this service does not classify natural language a second time. Context is explicitly preview or conversation. Provide one to thirteen messages with server-issued unique id and text (up to 4,000 characters). Provide up to thirty observations: kind, messageId, and an exact quote of 3–240 characters from that message. Unknown fields, duplicate IDs and invented/foreign quotes are rejected.

Kinds: credential_request, remote_access_request, safe_account_transfer, secrecy_pressure, impersonation, unrecognized_payment. Redact actual credentials and unnecessary personal details before AI processing. Do not request OTPs, PINs, passwords or full card details. The assessor neither stores nor echoes messages/quotes.

The result includes version, assessmentId, assessedAt, context, API-key mode, priority, handoffRequired and coded signals with source message IDs. All signals except secrecy alone require urgent handoff; secrecy alone requires review. No observations means no reported signals. Every result retains verdict: inconclusive, coverage: reported_signals_only, bankFactsChecked: false, callerIdentityEstablished: false, and moneyMovementPerformed: false. A matching quote proves only that the text exists, not that the interpretation or allegation is true.

The support platform owns case storage, staff priority, exactly-once delivery and stopping AI replies on staff takeover. A preview does not emit a real support escalation or claim a person is connected. For live conversations, invoke assessment after interpretation and before handoff priority; persist its ID/source references in the existing case audit. An enabled dependency failure is an error, never a normal/no-signal result.

Read-only bank checks

GET /capabilities reports the calling business/key mode and whether a matching bank gateway is configured. POST /checks accepts exactly:

{"kind":"support_request","reference":"REQ-123","customerAuthorization":"OPAQUE_BANK_ISSUED_GRANT"}

kind is support_request or payment. The bank's own customer authentication flow issues the opaque grant; this is not a transaction OTP. The bank gateway must verify its audience, subject, expiry and operation permission. The request accepts no customer/account ID, workspace override, target URL or free-form instructions. Caller ID, a phone number, contact match or video liveness alone does not authorize bank data access.

No live bank gateway is configured by this release. Missing configuration returns 503 BANK_CONNECTOR_NOT_CONFIGURED; denied customer authorization returns 403 BANK_AUTHORIZATION_DENIED; transport, invalid or stale evidence returns 502 BANK_CHECK_UNAVAILABLE. A bank may return a legitimate not_found fact. No case, freeze, recall, transfer or refund is executed. A matching bank support request does not authenticate the caller.

Operator configuration

Put the server-only JSON in Secret Manager, not a browser variable or source control. BANK_SUPPORT_CONNECTORS_JSON is keyed by the actual YeboVerify business ID; live and sandbox each have their own explicit gateway bankId, HTTPS origin and bearer token (32–2048 printable characters). There is no cross-mode or cross-tenant fallback. Invalid configuration fails visibly. An empty/missing mapping disables bank checks, not assessment.

Before adding a binding, describe the exact target service's runtime service account, grant that account access to the new secret, and add the binding with --update-secrets=BANK_SUPPORT_CONNECTORS_JSON=<approved-secret>:latest. Preserve all existing bindings. The feature needs no new database schema. Do not bind a fictional or demonstration gateway in production.

Gateway contract v1

YeboVerify POSTs to <configured-origin>/v1/support/checks, with the configured bearer token, an eight-second timeout, no redirects and the existing public-HTTPS SSRF guard. The gateway origin is operator configured and cannot be supplied by a customer. The JSON body is {version:1, mode, checkId, kind, reference, customerAuthorization, requestedAt}; checkId is a fresh UUID. The bank must authorize every request and never log grants.

HTTP 401 indicates a connector credential failure (returned as 502 BANK_CONNECTOR_AUTH_FAILED); HTTP 403 means the bank denied customer authorization. Successful replies must be bounded JSON (32 KiB maximum), include exactly the fields below, and echo mode, nonce, bank ID, reference and kind correctly:

{
  "version":1,"mode":"live","checkId":"<echoed UUID>","bankId":"<configured bank ID>",
  "kind":"support_request","reference":"REQ-123","checkedAt":"<current ISO timestamp>",
  "authorization":{"subjectRef":"<opaque bank customer>","expiresAt":"<ISO expiry>","permissions":["support_request:read"]},
  "result":{"status":"found","request":{"status":"active","action":"support_callback","expiresAt":"<ISO expiry>"}}
}

Evidence must be no more than 60 seconds old (five-second future-clock tolerance). The authorized enquiry window must still be valid and end within ten minutes. Permissions must include support_request:read or payment:read as appropriate. Evidence from a different request, bank, environment, reference or operation is rejected.

Support results are not_found, or found with request status active|expired|cancelled|completed, action identity_verification|payment|support_callback|document_request, and expiresAt. A payment action additionally requires integer amountMinor, ISO-style three-letter currency and payeeLabel; other actions omit those fields. An expired request never remains active in the returned result.

Payment results are not_found, or status pending|completed|failed|reversed with nonnegative integer amountMinor and three-letter currency. A completed payment is not a statement that it was authorized or that funds are recoverable.

Results add evidenceSource: bank_gateway, callerIdentityEstablished: false, and moneyMovementPerformed: false. Interpret them through the bank-approved customer interface; never promote free-text bank labels or transcripts to model instructions.

Validation and release limits

Automated tests use actual local HTTP and explicit simulated bank responses. They cover tenant/mode isolation, authentication, strict fields, stale and replay binding, grant permissions/expiry, redirects, denial, malformed/oversized responses, input evidence and current v1 router wiring. They do not establish a real bank integration, measured scam-detection performance, siSwati speech quality or payment-blocking capability. YeboLink owns and releases its Customer Care changes separately.