На странице
Серверные 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 |
| Python | PyPI | pip install paymos-sdk |
Paymos-labs/python-sdk |
| PHP | Packagist | composer require paymos/php-sdk |
Paymos-labs/php-sdk |
| Go | Go modules | go get github.com/Paymos-labs/go-sdk/v2 |
Paymos-labs/go-sdk |
| .NET | NuGet | dotnet add package Paymos |
Paymos-labs/dotnet-sdk |
| Java | Maven Central | io.paymos:paymos-java |
Paymos-labs/java-sdk |
| Ruby | RubyGems | gem install paymos |
Paymos-labs/ruby-sdk |
| Rust | crates.io | cargo add paymos |
Paymos-labs/rust-sdk |
У Java нет команды в одну строку: добавьте зависимость io.paymos:paymos-java
в pom.xml или в сборку Gradle.
Используйте неизменяемый релизный тег vMAJOR.MINOR.PATCH. На странице релизов
каждого репозитория указаны поддерживаемая версия runtime, changelog и исходный
commit, из которого собран релиз.
Единый интерфейс API
Во всех клиентах есть шесть ресурсов:
- —
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 под ними, а не восемь раз над ними. К остальным семи клиентам это не относится: в них есть клиент, подпись, ресурсы, постраничный обход и проверка вебхука — и больше ничего.
Правила безопасности
Эти SDK предназначены только для сервера. Никогда не помещайте API Secret в браузерный JavaScript, мобильное приложение, публичный репозиторий, URL или лог.
API-запросы и вебхуки подписываются по-разному. Для API используется base64
HMAC-SHA256 канонического запроса. Для вебхука — hex HMAC-SHA256 строки
{timestamp}.{точное исходное тело}. Передайте в проверку исходные байты запроса
до разбора JSON. По умолчанию проверка отклоняет метку времени, отличающуюся от
текущей больше чем на пять минут, и принимает заголовок с двумя значениями
v1 — смена секрета не требует правок в коде.
Схемы и примеры эндпоинтов: Аутентификация, Инвойсы, Выводы, Балансы и Вебхуки.