Подписанные запросы

В отличие от приёма платежей (где достаточно X-Api-Key), вывод средств - операция повышенного риска. Поэтому подписывать нужно все эндпоинты выплат:

• POST /integration/payouts - создание выплаты
• GET /integration/payouts/{uuid} - статус выплаты
• GET /integration/payouts - история выплат
• GET /integration/payouts/quote - предварительный расчёт

Заголовки

Строка подписи

Соедините четыре части символом перевода строки \n:

{timestamp}\n
{METHOD}\n
{path}\n
{sha256_hex(raw_body)}

• timestamp - то же значение, что в заголовке X-Timestamp
• METHOD - HTTP-метод в верхнем регистре (POST или GET)
• path - полный путь запроса включая префикс /api/v1, например /api/v1/integration/payouts. Без хоста и без query-строки - фильтры и пагинация в истории выплат на подпись не влияют
• sha256_hex(raw_body) - SHA-256 в hex от сырого тела. Для GET тело пустое - это sha256("")

Подпись: HMAC-SHA256(строка, api_secret) в hex, где api_secret - секрет мерчанта (sk_…).

Формирование заголовков

import crypto from "node:crypto";
 
function signedHeaders(method, path, rawBody, apiKey, apiSecret) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const body = method === "GET" || method === "HEAD" ? "" : rawBody;
  const bodyHash = crypto.createHash("sha256").update(body).digest("hex");
  const payload = [timestamp, method, path, bodyHash].join("\n");
  const signature = crypto
    .createHmac("sha256", apiSecret)
    .update(payload)
    .digest("hex");
 
  return {
    "X-Api-Key": apiKey,
    "X-Timestamp": timestamp,
    "X-Signature": signature,
    "Content-Type": "application/json",
  };
}
 
const path = "/api/v1/integration/payouts";
const body = JSON.stringify({ amount: 2500000, currency: "RUB",
  external_id: "withdraw-001" });
 
await fetch("https://api.cashera.cash" + path, {
  method: "POST",
  headers: signedHeaders("POST", path, body, PK, SK),
  body,
});

Белый список IP

Дополнительно мерчант может ограничить, с каких IP-адресов принимаются подписанные запросы. Если allowlist настроен в кабинете, запросы с других адресов отклоняются с 403. Запросы с разрешённых адресов проходят как обычно.

Ошибки подписи