{"id":21635236,"url":"https://github.com/kravetsone/t-kassa-api","last_synced_at":"2025-07-02T20:07:45.976Z","repository":{"id":247653016,"uuid":"826328538","full_name":"kravetsone/t-kassa-api","owner":"kravetsone","description":"Библиотека для взаимодействия с API Т-Кассы.","archived":false,"fork":false,"pushed_at":"2025-06-23T20:26:45.000Z","size":1061,"stargazers_count":18,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-23T21:33:22.079Z","etag":null,"topics":["payments","t-kassa","tinkoff","tinkoff-api","tinkoff-payment","tinkoff-sdk"],"latest_commit_sha":null,"homepage":"https://jsr.io/@kravets/t-kassa-api","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kravetsone.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-07-09T13:49:42.000Z","updated_at":"2025-06-23T20:26:48.000Z","dependencies_parsed_at":"2024-09-11T20:08:24.465Z","dependency_job_id":"8473d327-8ea6-43cc-ab3a-dfa9145d3f32","html_url":"https://github.com/kravetsone/t-kassa-api","commit_stats":null,"previous_names":["kravetsone/t-kassa-api"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/kravetsone/t-kassa-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kravetsone%2Ft-kassa-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kravetsone%2Ft-kassa-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kravetsone%2Ft-kassa-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kravetsone%2Ft-kassa-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kravetsone","download_url":"https://codeload.github.com/kravetsone/t-kassa-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kravetsone%2Ft-kassa-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261562012,"owners_count":23177706,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["payments","t-kassa","tinkoff","tinkoff-api","tinkoff-payment","tinkoff-sdk"],"created_at":"2024-11-25T03:20:20.131Z","updated_at":"2025-07-02T20:07:45.940Z","avatar_url":"https://github.com/kravetsone.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# t-kassa-api\n\n[![npm](https://img.shields.io/npm/v/t-kassa-api?logo=npm\u0026style=flat\u0026labelColor=000\u0026color=3b82f6)](https://www.npmjs.org/package/t-kassa-api)\n[![npm downloads](https://img.shields.io/npm/dw/t-kassa-api?logo=npm\u0026style=flat\u0026labelColor=000\u0026color=3b82f6)](https://www.npmjs.org/package/t-kassa-api)\n[![JSR](https://jsr.io/badges/@kravets/t-kassa-api)](https://jsr.io/@kravets/t-kassa-api)\n[![JSR Score](https://jsr.io/badges/@kravets/t-kassa-api/score)](https://jsr.io/@kravets/t-kassa-api)\n\n\u003c/div\u003e\n\nБиблиотека для взаимодействия с [API Т-Кассы](https://www.tbank.ru/kassa/dev/payments/index.html).\n\n```ts\nimport { TKassa } from \"t-kassa-api\";\n\nconst ткасса = new TKassa(process.env.TERMINAL_KEY, process.env.PASSWORD, {\n    server: \"https://rest-api-test.tinkoff.ru\",\n});\n\nconst result = await ткасса.init({\n    Amount: 1000,\n    OrderId: \"12\",\n});\n\nconsole.log(result);\n```\n\n[API Reference](https://jsr.io/@kravets/t-kassa-api/doc)\n\n\u003e [!IMPORTANT]\n\u003e [Тестовая среда доступна только по запросу](https://www.tbank.ru/kassa/dev/payments/#tag/Testovye-karty) - иначе вы будете получать ответы с кодом `403`\n\n### Фичи\n\n-   Генерируется исходя из **OpenAPI** спецификации\n-   Очень удобная работа с нотификацией (webhook) с умными фильтрами\n-   Имеет в себе [webhook адаптеры для самых популярных фреймворков](#поддерживаемые-webhook-адаптеры)\n-   Удобна и для [нескольких касс](#режим-мульти-кассы)\n-   Отличная документация кода с помощью **JSDoc** (сгенерировано из **OpenAPI**)\n-   Современная и с **умнейшими** типами\n-   0 зависимостей\n-   Берёт работу с [подписью запроса](https://www.tbank.ru/kassa/dev/payments/index.html#section/Podpis-zaprosa) на себя\n-   [Есть на JSR](https://jsr.io/@kravets/t-kassa-api)\n\n### Webhook\n\nПример использования webhook с фреймворком [Hono](https://hono.dev/)\n\n```ts\nimport { Hono } from \"hono\";\nimport { TKassa, webhookHandler, filters } from \"t-kassa-api\";\n\nconst ткасса = new TKassa(process.env.TERMINAL_KEY, process.env.PASSWORD);\n\nткасса.on(\n    filters.and(\n        filters.equal(\"Status\", \"SUCCESS\"),\n        filters.notNullable(\"RebillId\")\n    ),\n    (context) =\u003e {\n        // при этом типы понимают фильтры\n    }\n);\n\nconst app = new Hono();\n\napp.get(\"/\", webhookHandler(ткасса, \"hono\"));\n```\n\n### Поддерживаемые webhook адаптеры\n\n-   [Elysia](https://elysiajs.com/)\n-   [Fastify](https://fastify.dev/)\n-   [Hono](https://hono.dev/)\n-   [Express](https://expressjs.com/)\n-   [Koa](https://koajs.com/)\n-   [node:http](https://nodejs.org/api/http.html)\n-   [Bun.serve](https://bun.sh/docs/api/http)\n-   [std/http (Deno.serve)](https://docs.deno.com/runtime/manual/runtime/http_server_apis#http-server-apis)\n\nили любой другой фреймворк\n\n```ts\n// a non-existing framework for the example\nimport { App } from \"some-http-framework\";\nimport { TKassa } from \"t-kassa-api\";\n\nconst ткасса = new TKassa(process.env.TERMINAL_KEY, process.env.PASSWORD, {\n    server: \"https://rest-api-test.tinkoff.ru\",\n});\n\nconst app = new App().post(\"/t-kassa\", async (req) =\u003e {\n    // req.body must be json equivalent to Webhook notification body\n    await ткасса.emit(req.body);\n});\n\napp.listen(80);\n```\n\n### Режим мульти-кассы\n\nНе всегда бывает удобным передача параметров одной кассы в конструктор класса, поэтому и появился режим мульти-кассы. Он позволяет вам не указывать `TerminalKey` и `Password`.\n\n```ts\nimport { TKassa } from \"t-kassa-api\";\n\nconst ткасса = new TKassa();\n\nconst result = await ткасса.init({\n    Amount: 1000,\n    OrderId: \"12\",\n    TerminalKey: \"12312sf\",\n    Password: \"123123231\",\n});\n\nconsole.log(result);\n```\n\nИ как вы можете заметить, теперь требуется указывать `TerminalKey` и `Password` в теле запроса. И в типах это тоже выражено! Магия? Не иначе.\n\nНо как тогда получать webhook события? (нотификацию)\n\nДля этого вам понадобится указать функцию первым аргументом конструктора.\n\n```ts\nimport { TKassa } from \"t-kassa-api\";\n\nconst ткасса = new TKassa((body) =\u003e {\n    const [kassa] = await db\n        .select()\n        .from(kassaTable)\n        .where(eq(kassaTable.terminalKey, body.TerminalKey));\n\n    if (!kassa) throw new Error(\"Касса не найдена\");\n\n    return {\n        Password: kassa.password,\n        custom: { kassa },\n    };\n});\n\nткасса.on(\n    filters.and(\n        filters.equal(\"Status\", \"SUCCESS\"),\n        filters.notNullable(\"RebillId\")\n    ),\n    (context, { kassa }) =\u003e {\n        // и тут появляется вторым аргументов переданное вами значение в custom\n    }\n);\n```\n\nИ типы опять же совсем не глупы и делают вам благое дело, указывая верный путь.\n\n### RequestsOptions\n\nВы можете повлиять на поведение запроса\n\n#### Глобально\n\n```ts\nconst tKassa = new TKassa({\n    requestsOptions: {\n        headers: {\n            \"x-awesome\": \"this library is great\",\n        },\n    },\n});\n```\n\n#### Для одного запроса\n\n```ts\nawait tKassa.getQr(/** some data */, {\n    signal: AbortSignal.timeout(500)\n});\n```\n\nТаким образом вы можете, например, воспользоваться прокси.\n\nВ [Node.js](https://nodejs.org/)\n\n```ts\nimport { ProxyAgent } from \"undici\";\n\nconst proxyAgent = new ProxyAgent(\"my.proxy.server\");\n\nconst tKassa = new TKassa({\n    requestsOptions: {\n        dispatcher: proxyAgent,\n    },\n});\n```\n\nНесмотря на то что `undici` работает под капотом `Node.js`, вам придётся его скачать. Также убедитесь, что у вас нет `\"lib\": [\"DOM\"]` в вашем `tsconfig.json`, иначе вы не увидите свойства `dispatcher` (хотя `undici` всё равно его обработает).\n\nВ [Bun](https://bun.sh)\n\n```ts\nconst tKassa = new TKassa({\n    requestsOptions: {\n        proxy: \"my.proxy.server\",\n    },\n});\n```\n\n### Функции-хелперы\n\n##### [`generateSignature`](https://jsr.io/@kravets/t-kassa-api/doc/~/generateSignature)\n\nГенерирует подпись для запроса.\n\n```ts\nconst signature = generateSignature(\n    { body: \"OK\" },\n    process.env.TERMINAL_KEY,\n    process.env.PASSWORD\n);\n```\n\n##### [`encryptCardData`](https://jsr.io/@kravets/t-kassa-api/doc/~/encryptCardData)\n\nШифрует данные карты.\n\n```ts\nconst cardData = encryptCardData(тк, {\n    PAN: \"4000000000000101\",\n    ExpDate: \"1230\",\n    CVV: \"111\",\n});\n\nconst tds = await тк.check3dsVersion({\n    PaymentId: response.PaymentId,\n    CardData: cardData,\n});\n```\n\n##### [`fetchACSUrl`](https://jsr.io/@kravets/t-kassa-api/doc/~/fetchACSUrl)\n\nФункция, которая отправляет запрос в сервис аутентификации банка (по `ACSUrl`) в зависимости от версии `3D-Secure`. Возвращает [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) с HTML формочкой, которую браузер сабмитнет сразу. Вместо этого метода рекомендуется использовать элемент `form` в `\u003cbody onload=\"document.form.submit()\"\u003e`.\n\n```ts\nconst response = await fetchACSUrl(finishAuthorize.ACSUrl, threeDS.version, {\n    MD: finishAuthorize.MD,\n    PaReq: finishAuthorize.PaReq,\n    TermURL: \"https://example.com\",\n    // other data\n});\n```\n\n[Подробнее](https://www.tbank.ru/kassa/dev/payments/index.html#tag/Scenarii-oplaty-po-karte/Scenarii-platezha)\n\n##### [`encryptCReq`](https://jsr.io/@kravets/t-kassa-api/doc/~/encryptCReq)\n\nФункция для получения строкового представления `creq` (нужен для 3DS 2.0)\n\n```ts\nconst str = encryptCReq({\n    threeDSServerTransID: data.threeDSServerTransID,\n    acsTransID: data.acsTransID,\n    challengeWindowSize: data.challengeWindowSize,\n    messageType: \"CReq\",\n    messageVersion: threeDS.version,\n});\n```\n\n##### [`encryptThreeDSMethodData`](https://jsr.io/@kravets/t-kassa-api/doc/~/encryptThreeDSMethodData)\n\nФункция для получения строкового представления `ThreeDSMethodData`\n\n```ts\nconst tds = await тк.check3dsVersion({\n    PaymentId: response.PaymentId,\n    CardData: CardData,\n});\n\nif (tds.ThreeDSMethodURL \u0026\u0026 tds.TdsServerTransID) {\n    const data = encryptThreeDSMethodData({\n        threeDSMethodNotificationURL: tds.ThreeDSMethodURL,\n        threeDSServerTransID: tds.TdsServerTransID,\n    });\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkravetsone%2Ft-kassa-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkravetsone%2Ft-kassa-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkravetsone%2Ft-kassa-api/lists"}