# Integrate Tole Payments API

Use this brief inside the repository that needs Tole payment automation.

## Authoritative contract

- OpenAPI 3.1: https://api.tolepay.kz/v1/openapi.json
- Human guide: https://tolepay.kz/ru/docs
- Base URL: `https://api.tolepay.kz/v1`
- Cashier setup: https://tolepay.kz/ru/docs/kaspi-cashier

The live OpenAPI document is the source of truth. Do not invent fields, SDKs,
routes, statuses, response shapes, or webhook events.

## Before editing code

1. Inspect the repository stack, existing HTTP client, environment conventions,
   persistence, background jobs, and test setup.
2. Read the current OpenAPI document.
3. Keep all Tole credentials server-side. Add `TOLE_API_KEY` and optional
   `TOLE_CONNECTION_ID` to the existing secret system. Never expose them to a
   browser bundle or logs.

## Implementation requirements

1. Create a small typed Tole adapter around the repository's existing HTTP
   client. Send `Authorization: Bearer <tole_sk_...>`, `Content-Type:
   application/json`, and `X-Tole-Connection-Id` when configured.
2. Implement the requested invoice or QR flow using the exact OpenAPI schemas.
3. For every mutation send a stable `Idempotency-Key` derived from the local
   business operation ID. Do not generate a new random key on every retry.
4. Persist Tole's local resource `id` and `commandId`. Never treat a private
   Kaspi identifier as a public `operationId`.
5. Handle `200/201` as complete. For `202 in_progress`, honor `Retry-After` and
   poll `Location` or `GET /commands/{commandId}`. For `202 outcome_unknown`,
   never automatically repeat the mutation; reconcile command and payment
   intent state.
6. Verify webhooks over the exact raw request body before JSON parsing:
   `v1=hex(HMAC-SHA256(secret,
   "<webhook-id>.<webhook-timestamp>.<exact_body>"))`. Guard timestamp replay,
   deduplicate `webhook-id`, persist before processing, and return `2xx` only
   after durable acceptance.
7. Use bounded timeouts. Retry safe reads with exponential backoff. Never
   blindly retry payment mutations, `4xx` responses, or unknown outcomes.
8. Add redacted structured logs. Never log API keys, webhook secrets, phone
   numbers, raw provider payloads, QR tokens, or payment URLs.
9. Test success, validation failure, `401/403`, `409`, `429`, both `202`
   outcomes, valid/invalid webhook signatures, duplicate events, and timeout.
10. Exercise `/v1/sandbox/*` with a test API key and required
    `X-Tole-Connection-Id` before live mode. Do not simulate success in
    production code.

## Deliverables

- production adapter and domain mapping;
- environment documentation without real secrets;
- webhook endpoint and signature verification;
- automated tests and a copy-pasteable sandbox smoke command;
- handoff listing changed files, checks, and remaining live-only verification.

If a credential, connection ID, webhook URL, or business mapping is missing,
finish all safe local work first and ask only for that missing value. Never ask
the user to paste a secret into chat.