Подпись запросов Payout API

Доступ

Функциональность выводов подключается по запросу — по умолчанию она недоступна. Направления подключаются отдельно: выводы на карты, выводы в криптовалюту и выводы по СБП. Для получения доступа обратитесь к вашему менеджеру. После подключения в личном кабинете появится раздел Payout API.

Секретный ключ

Все запросы к Payout API подписываются секретным ключом (SECRET). Ключ свой у каждого направления: ключом карточных выводов нельзя подписать вывод в криптовалюту или по СБП.

Ключ выдаётся через личный кабинет и хранится только у вас — Platega не имеет к нему доступа после выдачи. Ключ показывается один раз сразу после генерации — немедленно сохраните его. Повторно просмотреть невозможно.

Сброс ключа

Если ключ утерян или скомпрометирован — сбросьте его через раздел Payout API в личном кабинете. Потребуется подтверждение кодом из email. Новый ключ также показывается один раз. Сброс немедленно инвалидирует старый ключ — все запросы, подписанные им, начнут возвращать ошибку аутентификации.

Ограничение по IP

Для ключа можно задать список разрешённых IP-адресов. Если список задан, запросы с других адресов отклоняются с ошибкой аутентификации ещё до проверки подписи. Если список пуст, ограничение не применяется. Список задаётся для каждого ключа отдельно. Настраивается через вашего менеджера.

Подпись запроса (HMAC-SHA256)

Каждый запрос должен быть подписан. Строка для подписи, элементы разделены символом перевода строки:

METHOD\nPATH\ntimestamp\nidempotency-key\nsha256_hex(body)

METHOD — метод запроса в верхнем регистре

PATH — путь запроса без хоста и без строки запроса

timestamp — unix-время в секундах. Сервер принимает запросы в окне ±300 секунд

idempotency-key — уникальная строка для каждого вывода, генерируется на стороне клиента (например, UUID). Та же строка передаётся в заголовке Idempotency-Key

sha256_hex(body) — SHA-256 от тела запроса, hex строчными буквами. Тело сериализуется без лишних пробелов — те же байты идут и в подпись, и в запрос

Подпись: Base64(HMAC-SHA256(SECRET, string_to_sign))

Заголовок авторизации: Authorization: PG-HMAC kid={MERCHANT_ID}, ts={timestamp}, sig={подпись}

Рассчитанная подпись одноразовая: повторная отправка того же значения в течение 300 секунд отклоняется.

Подпись GET-запросов

У справочников — сохранённые карты, криптокошельки, получатели и банки СБП — тела нет, и Idempotency-Key в них не передаётся. Соответствующий элемент строки подписи остаётся пустым, а вместо хеша тела подставляется хеш пустой строки:

GET\n/api/v1/sbp-banks\n1719403200\n\ne3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Хеш пустой строки всегда один и тот же: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

Ошибка авторизации

Все случаи сводятся к коду 401 и общей формулировке ответа: недействительная или просроченная подпись, выход за пределы окна, неизвестный ключ, IP вне списка разрешённых, отключённое направление выводов. Конкретика приходит в поле message.

Пример формирования подписи (Python)

Для GET-запроса к справочнику в этом примере меняются три строки: метод GET, пустой ключ идемпотентности и хеш пустого тела.

Подпись запросов Payout API

Доступ#

Секретный ключ#

Сброс ключа#

Ограничение по IP#

Подпись запроса (HMAC-SHA256)#

Подпись GET-запросов#

Ошибка авторизации#

Пример формирования подписи (Python)#