На странице
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 — пока в дашборде не указан хотя бы один адрес, любой запрос с таким ключом отклоняется. Свежесозданный ключ Payout сам по себе средства не выведет.
Ключ Payout может вывести средства с вашего баланса в Paymos — относитесь к нему как к паролю от банка. Список разрешённых IP — это стена между украденным ключом и вашими деньгами, поэтому держите его как можно уже: вносите только те IP серверов, которые действительно обращаются к API выводов.
Жизненный цикл
| Статус | Описание |
|---|---|
| Active | Ключ активен и принимает запросы |
| Revoked | Конечный статус. Ключ отключён навсегда, восстановить его нельзя |
Рекомендации по безопасности
- —Никогда не передавайте API-секрет в клиентский код
- —Регулярно меняйте секреты через дашборд — на время перехода предыдущий секрет ещё действует благодаря льготному периоду
- —Используйте разные ключи для рабочего и тестового режима
- —Ограничивайте ключи Payout по IP
- —Храните API-секреты только в переменных окружения или в менеджере секретов
Схему подписи HMAC-SHA256, которая использует эти ключи, смотрите в разделе «Аутентификация».