# Серверные SDK

> Используйте официальные клиенты Merchant API для JavaScript/TypeScript, Python, PHP, Go, .NET, Java, Ruby и Rust с типизированными запросами и HMAC.

Paymos поддерживает официальные серверные SDK для восьми языковых экосистем. Во
всех SDK одинаковый контракт: инвойсы, выводы, платёжные каналы, депозиты
каналов, балансы, серверное время, курсорная пагинация, ошибки, повторы
запросов, подпись API и проверка вебхуков.

Все восемь клиентов опубликованы в реестрах пакетов своих экосистем.
Устанавливайте из реестра; в репозитории лежит исходный код и история релизов.

| Язык | Реестр пакетов | Установка | Официальный репозиторий |
|---|---|---|---|
| JavaScript / TypeScript | npm | `npm i @paymos/sdk` | [Paymos-labs/typescript-sdk](https://github.com/Paymos-labs/typescript-sdk) |
| Python | PyPI | `pip install paymos-sdk` | [Paymos-labs/python-sdk](https://github.com/Paymos-labs/python-sdk) |
| PHP | Packagist | `composer require paymos/php-sdk` | [Paymos-labs/php-sdk](https://github.com/Paymos-labs/php-sdk) |
| Go | Go modules | `go get github.com/Paymos-labs/go-sdk/v2` | [Paymos-labs/go-sdk](https://github.com/Paymos-labs/go-sdk) |
| .NET | NuGet | `dotnet add package Paymos` | [Paymos-labs/dotnet-sdk](https://github.com/Paymos-labs/dotnet-sdk) |
| Java | Maven Central | `io.paymos:paymos-java` | [Paymos-labs/java-sdk](https://github.com/Paymos-labs/java-sdk) |
| Ruby | RubyGems | `gem install paymos` | [Paymos-labs/ruby-sdk](https://github.com/Paymos-labs/ruby-sdk) |
| Rust | crates.io | `cargo add paymos` | [Paymos-labs/rust-sdk](https://github.com/Paymos-labs/rust-sdk) |

У Java нет команды в одну строку: добавьте зависимость `io.paymos:paymos-java`
в `pom.xml` или в сборку Gradle.

Используйте неизменяемый релизный тег `vMAJOR.MINOR.PATCH`. На странице релизов
каждого репозитория указаны поддерживаемая версия runtime, changelog и исходный
commit, из которого собран релиз.

## Единый интерфейс API

Во всех клиентах есть шесть ресурсов:

:::dash-list
- `system` — получить серверное время для синхронизации часов запросов
- `invoices` — создать, получить, перечислить, отменить, подтвердить оплату и запустить тестовую симуляцию
- `withdrawals` — создать, получить, перечислить, отменить и запустить тестовую симуляцию завершения
- `paymentChannels` — создать, получить, перечислить, заблокировать, разблокировать и симулировать депозит в тестовом режиме
- `paymentChannelDeposits` — получить один депозит и читать ленту подтверждённых депозитов
- `balances` — получить доступные балансы с группировкой по валюте
:::

Два канальных ресурса каждый клиент пишет по правилам своего языка:
`paymentChannels` в TypeScript, PHP и Java, `payment_channels` в Python, Ruby и
Rust, `PaymentChannels` в Go и .NET.

Методы списков используют курсорную пагинацию с ограничением числа страниц и
отклоняют повторно возвращённый курсор. Автоматические повторы учитывают
`Retry-After`; изменяющие состояние запросы не повторяются после сетевой ошибки
или обычной серверной ошибки. Запрос, отклонённый по лимиту частоты, повторить можно: API не принял его в
обработку.

## Один контракт на восемь языков

Совпадает не только список эндпоинтов, но и поведение. Единый набор проверок,
не зависящий от языка, задаёт байты, которые уходят в подпись запроса, правила
повторов выше, обход курсоров и проверку вебхука; релиз выходит только после
того, как собственные тесты SDK прогоняются против этого набора.

Что это даёт на практике: интеграцию можно перенести с одного языка на другой,
и подпись, постраничный обход, повторы и разбор вебхука останутся прежними. Два
SDK на один и тот же запрос со списком подпишут одинаковые байты.

## Что есть только в PHP

У PHP-SDK есть слой для интеграции с CMS, которого нет ни в одном другом
клиенте: обратная сверка вебхука со свежим чтением API, проверка суммы и валюты
перед выдачей заказа, защита от повторной обработки события через подключаемое
хранилище, проверяющий, который держит тестовый и рабочий секреты одновременно,
сверка расхождений, преобразование события в действие над заказом и шифрованное
хранение ключей.

Из-за этого слоя плагины для CMS такие тонкие: логика состояний заказа лежит
один раз в SDK под ними, а не восемь раз над ними. К остальным семи клиентам
это не относится: в них есть клиент, подпись, ресурсы, постраничный обход и
проверка вебхука — и больше ничего.

## Правила безопасности

:::warning
Эти SDK предназначены только для сервера. Никогда не помещайте API Secret в
браузерный JavaScript, мобильное приложение, публичный репозиторий, URL или лог.
:::

API-запросы и вебхуки подписываются по-разному. Для API используется base64
HMAC-SHA256 канонического запроса. Для вебхука — hex HMAC-SHA256 строки
`{timestamp}.{точное исходное тело}`. Передайте в проверку исходные байты запроса
до разбора JSON. По умолчанию проверка отклоняет метку времени, отличающуюся от
текущей больше чем на пять минут, и принимает заголовок с двумя значениями
`v1` — [смена секрета](/ru/docs/webhooks/verify.md) не требует правок в коде.

Схемы и примеры эндпоинтов: [Аутентификация](/ru/docs/authentication.md),
[Инвойсы](/ru/docs/invoices/create.md), [Выводы](/ru/docs/withdrawals/create.md),
[Балансы](/ru/docs/balances/get.md) и [Вебхуки](/ru/docs/webhooks.md).