# Banking voice-agent tool-call contract template

Copy this into a design review before connecting a conversational model to any money-moving service. Every field and example below is fictional. Replace it with your bank or payment provider’s approved schema, authentication flow, limits, and policy.

## Boundary statement

> The language model may propose intent and quote caller evidence. Only deterministic services resolve customer records, validate fields, apply policy, authorize the transaction, and commit it once.

## 1. Observation from the conversation

```json
{
  "amount_phrase": "five thousand",
  "beneficiary_phrase": "Rakesh HDFC Baner",
  "rail_phrase": null,
  "caller_correction_turns": [],
  "evidence_turn_ids": [31, 32]
}
```

Rules:

- No account, IFSC, UPI, amount, or beneficiary is treated as verified because the model emitted valid JSON.
- Preserve corrections and the turn IDs that support the proposal.
- Missing or ambiguous fields stay missing. Never fabricate a plausible value.

## 2. Resolved candidate owned by code

```json
{
  "transaction_id": "txn_example_7f2",
  "amount_minor": 500000,
  "currency": "INR",
  "beneficiary_id": "ben_example_1842",
  "rail": "IMPS",
  "resolution_evidence": {
    "beneficiary_match": "single_saved_match",
    "account_status": "active"
  },
  "expires_at": "2026-07-15T12:05:00Z"
}
```

Server checks:

- [ ] Exact types and allowed values.
- [ ] Customer session and account are current.
- [ ] Beneficiary is resolved from approved records.
- [ ] Amount and currency satisfy product limits.
- [ ] Rail is allowed for this beneficiary and amount.
- [ ] Fraud and policy services returned an approved state.
- [ ] Candidate expires quickly and cannot be edited by the model.

## 3. Confirmation contract

Build spoken confirmation from the resolved candidate:

```text
I have ₹5,000 to Rakesh Sharma, beneficiary ending 1842, by IMPS. Shall I continue?
```

Reject or restart confirmation when:

- the caller changes amount, payee, account, date, or rail;
- speech contains a question instead of clear approval;
- approval comes from background audio;
- the candidate expires;
- risk or account state changes.

## 4. Commit request

```json
{
  "transaction_id": "txn_example_7f2",
  "authorization_token": "opaque_short_lived_value",
  "confirmation_version": 3,
  "idempotency_key": "server_generated_unique_value"
}
```

The endpoint must return the same prior result for a safe retry with the same idempotency key. A timeout after commit must not create a second payment.

## 5. Logging rules

Log state, policy result, tool-call ID, hashed idempotency reference, and final outcome. Mask or exclude full account numbers, authentication secrets, OTP values, raw authorization tokens, and unrestricted payload dumps.

## 6. Minimum failure pack

- Valid schema, wrong beneficiary.
- Right IFSC shape, no matching branch record.
- Caller correction during read-back.
- Duplicate commit request.
- Expired confirmation.
- Tool timeout after successful debit.
- Background “yes.”
- Amount changes after authorization.
- Log search for a fictional OTP and account number returns no secret values.

## Approval

```text
Workflow owner:
Payment-service owner:
Fraud / risk approver:
Security approver:
Voice evaluation owner:
Schema version:
Policy version:
Open exception, owner, expiry:
Release decision:
```