API

На странице

API-ключи

Создавайте API-ключи Payment и Payout, разбирайтесь в правах и префиксах, безопасно меняйте секреты и разделяйте тестовый и рабочий доступ.

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

Типы ключей

Тип	Префикс	Права
Payment	`pk_`	Создавать инвойсы, читать статус, управлять платёжными каналами и читать их депозиты
Payout	`rk_`	Создавать выводы, отменять выводы, читать балансы

У API-секретов префикс sk_. У секретов для подписи вебхуков — whsec_.

Окружения

Каждый ключ привязан к одному окружению. Окружение закодировано в префиксе:

Окружение	Модификатор	Пример
Рабочий режим	`_live_`	`pk_live_…`, `rk_live_…`
Тестовый режим	`_test_`	`pk_test_…`, `rk_test_…`

Полностью настроенный мерчант хранит восемь значений: четыре идентификатора ключей (pk_live_…, pk_test_…, rk_live_…, rk_test_…) и по секрету sk_ к каждому из них. Секреты вебхуков считаются отдельно — whsec_ выдаётся не на окружение, а на каждый адрес доставки, и адресов в окружении может быть несколько; см. Вебхуки.

Как устроены права

Права разделены централизованно, а не на уровне отдельных маршрутов: уровень доступа выводится из типа ключа на каждом запросе. Поэтому ключ Payment (pk_) видит только эндпоинты приёма денег, а ключ Payout (rk_) только эндпоинты вывода: создать вывод, отменить вывод, прочитать балансы.

Платёжные каналы относятся к приёму денег. Все восемь методов каналов и депозитов требуют ключ Payment и отвечают 403 payment_key_required на ключ Payout — зеркально тому, как выводы отклоняют ключ Payment.

Балансы удивляют чаще всего: GET /v1/balances требует ключ Payout. Ключ Payment живёт на серверах магазина, попадает в каждый выкат и утекает первым — поэтому видеть, сколько у вас на балансе, ему не положено. Читайте балансы оттуда же, откуда запускаете выводы.

К ключу Payout можно добавить список разрешённых IP — в дашборде и, пока белый список адресов для вывода включён, по желанию. Если в списке есть адреса, запрос с любого другого отклоняется с ip_not_allowed. Если список пуст, ключ работает с любого адреса: так и нужно для serverless-функции или хостинга без постоянного исходящего IP. У ключа Payment такого списка нет вовсе.

Если владелец отключил белый список адресов через поддержку, список IP у рабочего ключа Payout становится обязательным. Без единого IP выводы с ключа отклоняются с ip_allowlist_required, а последний IP не удалить, пока белый список адресов снова не включат.

Ключ Payout может вывести средства с вашего баланса в Paymos — относитесь к нему как к паролю от банка. По умолчанию нового получателя ключ не назначит: вывод уходит только на адрес из белого списка для вывода, а этот список меняется только в дашборде — и, если подключён второй фактор, со свежим подтверждением. Без белого списка ключ выводит на любой адрес, и пустить его в ход с чужого сервера мешает только список разрешённых IP. Если у ваших серверов постоянные IP, внесите их в список ключа, без лишних адресов.

Жизненный цикл

Статус	Описание
Active	Ключ активен и принимает запросы
Revoked	Конечный статус. Ключ отключён навсегда, восстановить его нельзя