01Авторизация и подписьAuthentication & signing

Каждый запрос идентифицируется API-ключом и подписывается HMAC-SHA256 вашим секретом.

Every request is identified by your API key and signed with HMAC-SHA256 using your secret.

При подключении вы получаете две строки — они показываются один раз, храните их только на сервере:

During onboarding you receive two strings — they are shown once, keep them on your server only:

• API-ключ (YOUR_MERCHANT_KEY) — передаётся в заголовке Authorization;
• API key (YOUR_MERCHANT_KEY) — sent in the Authorization header;
• HMAC-секрет (YOUR_HMAC_SECRET) — ключ подписи ваших запросов и наших вебхуков. Сам секрет в запросах не передаётся.
• HMAC secret (YOUR_HMAC_SECRET) — the signing key for your requests and our webhooks. The secret itself is never sent.

Заголовки

Headers

Строка подписи (v2)

Signing string (v2)

Поля склеиваются через перевод строки \n (без завершающего перевода строки). Отправляйте заголовок X-Signature-Version: 2.

Fields are joined with a newline \n (no trailing newline). Send the header X-Signature-Version: 2.

X-Signature = hex( HMAC_SHA256( YOUR_HMAC_SECRET,
    "v2"              + "\n" +
    timestamp         + "\n" +
    METHOD            + "\n" +
    path_with_query   + "\n" +
    idempotency_key   + "\n" +
    canonical_json ) )

• v2 — литерал, версия формата;
• v2 — a literal, the format version;
• timestamp — то же значение, что в X-Timestamp;
• timestamp — the same value as in X-Timestamp;
• METHOD — GET / POST в верхнем регистре;
• METHOD — GET / POST in upper case;
• path_with_query — путь и query-строка ровно как в URL запроса, без домена: /api/v1/merchant/requests, /api/v1/merchant/payin/proof?public_id=PI-…. Отправляете с завершающим / — подписывайте тоже с ним;
• path_with_query — the path and query string exactly as in the request URL, without host: /api/v1/merchant/requests, /api/v1/merchant/payin/proof?public_id=PI-…. If you send a trailing /, sign it too;
• idempotency_key — значение X-Idempotency-Key; если заголовка нет (GET) — пустая строка;
• idempotency_key — the X-Idempotency-Key value; empty string if there is no such header (GET);
• canonical_json — тело JSON с рекурсивно отсортированными ключами, без пробелов. Для GET и для multipart-запросов — строка {}.
• canonical_json — the JSON body with recursively sorted keys, no whitespace. For GET and multipart requests — the literal {}.

const crypto = require('crypto');

const API_KEY = 'YOUR_MERCHANT_KEY';
const HMAC_SECRET = 'YOUR_HMAC_SECRET';

// JSON with recursively sorted keys, no whitespace
function canonical(v) {
  const sort = (x) => Array.isArray(x) ? x.map(sort)
    : x && typeof x === 'object'
      ? Object.keys(x).sort().reduce((o, k) => (o[k] = sort(x[k]), o), {})
      : x;
  return JSON.stringify(sort(v ?? {}));
}

// path — path + query exactly as in the URL; idemKey — X-Idempotency-Key (POST) or ''
function signedHeaders(method, path, body, idemKey = '') {
  const ts = String(Math.floor(Date.now() / 1000));
  const payload = method === 'GET' ? '{}' : canonical(body);
  const msg = ['v2', ts, method, path, idemKey, payload].join('\n');
  const sig = crypto.createHmac('sha256', HMAC_SECRET).update(msg, 'utf8').digest('hex');
  const headers = {
    'Authorization': `Bearer ${API_KEY}`,
    'X-Timestamp': ts,
    'X-Signature-Version': '2',
    'X-Signature': sig,
    'Content-Type': 'application/json',
  };
  if (idemKey) headers['X-Idempotency-Key'] = idemKey;
  return headers;
}

import hashlib, hmac, json, time

API_KEY = "YOUR_MERCHANT_KEY"
HMAC_SECRET = "YOUR_HMAC_SECRET"

def canonical(body) -> str:
    # sorted keys, no whitespace, keep UTF-8 as is
    return json.dumps(body or {}, sort_keys=True,
                      separators=(",", ":"), ensure_ascii=False)

def signed_headers(method: str, path: str, body=None, idem_key: str = "") -> dict:
    ts = str(int(time.time()))
    payload = "{}" if method == "GET" else canonical(body)
    msg = "\n".join(["v2", ts, method, path, idem_key, payload]).encode("utf-8")
    sig = hmac.new(HMAC_SECRET.encode(), msg, hashlib.sha256).hexdigest()
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "X-Timestamp": ts,
        "X-Signature-Version": "2",
        "X-Signature": sig,
        "Content-Type": "application/json",
    }
    if idem_key:
        headers["X-Idempotency-Key"] = idem_key
    return headers

TS=$(date +%s)
P="/api/v1/merchant/limits"
# v2\n{ts}\nGET\n{path}\n{idempotency_key — empty for GET}\n{}
SIG=$(printf 'v2\n%s\nGET\n%s\n\n{}' "$TS" "$P" \
  | openssl dgst -sha256 -hmac "YOUR_HMAC_SECRET" | awk '{print $NF}')

curl -s "https://api.slipstream.cash$P" \
  -H "Authorization: Bearer YOUR_MERCHANT_KEY" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature-Version: 2" \
  -H "X-Signature: $SIG"

Подпись v1 (устаревшая)

Signature v1 (deprecated)

X-Signature = hex( HMAC_SHA256( YOUR_HMAC_SECRET,
                 "{timestamp}.{METHOD}.{path}{canonical_json}" ) )   // path — without query string

Дополнительная защита

Additional protection

• IP-allowlist. Если для вашего аккаунта заданы разрешённые IP, корректно подписанные запросы с других адресов получают 403 (адрес в ответе не раскрывается). Пустой список — доступ с любого IP.
• IP allowlist. If allowed IPs are configured for your account, correctly signed requests from other addresses get 403 (the address is not echoed back). Empty list — any IP is allowed.
• Перевыпуск. Ключ и секрет можно перевыпустить в кабинете мерчанта (раздел «Интеграция») или через менеджера. Старый ключ перестаёт работать сразу; новый секрет сразу используется и для подписи новых вебхуков.
• Rotation. Key and secret can be rotated in the merchant cabinet (“Integration”) or via your manager. The old key stops working immediately; the new secret is used for new webhook signatures right away.

02Быстрый стартQuick start

Три шага от ключей до первого подтверждённого платежа.

Three steps from keys to the first confirmed payment.

1. Проверьте доступ и методыCheck access and methods Вызовите GET /limits — это проверит подпись и покажет, какие методы вам подключены и доступны сейчас (available: true), и в каких пределах сумм. Call GET /limits — it verifies your signature and shows which methods are enabled and currently available for you (available: true) and their amount range.
2. Создайте заявкуCreate a request POST /requests с методом, суммой и callback_url. В ответе — public_id и requisites (карта / телефон / ссылка). Покажите их покупателю. POST /requests with a method, amount and callback_url. The response contains public_id and requisites (card / phone / link). Show them to the customer.
3. Примите вебхукReceive the webhook Проверьте X-Signature-V2 (см. Вебхуки), найдите заказ по merchant_request_id / public_id и проведите его при Confirmed. Для методов *_check после оплаты отправьте чек через POST /payin/proof. Verify X-Signature-V2 (see Webhooks), find the order by merchant_request_id / public_id and fulfil it on Confirmed. For *_check methods, upload the receipt via POST /payin/proof after payment.

// signedHeaders(), canonical() — from the “Authentication” section
const HOST = 'https://api.slipstream.cash';

async function call(method, path, body, idemKey = '') {
  // v2: X-Idempotency-Key входит в подпись / is part of the signature
  const headers = signedHeaders(method, path, body, idemKey);
  const res = await fetch(HOST + path, {
    method, headers,
    body: method === 'POST' ? canonical(body) : undefined,
  });
  return res.json();
}

async function main() {
  const limits = await call('GET', '/api/v1/merchant/limits');
  console.log(limits.data.methods.filter((m) => m.available));

  const order = {
    merchant_request_id: 'order-10001',
    sub_direction: 'payin_simple',
    preferred_method: 'c2c',
    client_amount: '5000.00',
    client_bank: 'any',
    client_requisites: 'customer-42',
    callback_url: 'https://merchant.example.com/webhook',
  };
  const r = await call('POST', '/api/v1/merchant/requests', order, order.merchant_request_id);
  console.log(r.data.public_id, r.data.status, r.data.requisites);
}
main();

03Создание заявкиCreate a request

Один эндпоинт для приёма (payin) и выплат (payout) — направление задаётся sub_direction. POST /requests/simple принимает то же тело и работает идентично.

One endpoint for pay-ins and payouts — direction is set by sub_direction. POST /requests/simple accepts the same body and behaves identically.

Параметры тела

Body parameters

Запрос

Request

# body is already canonical: keys sorted, no whitespace
BODY='{"callback_url":"https://merchant.example.com/webhook","client_amount":"5000.00","client_bank":"tinkoff","client_full_name":"Иван Иванов","client_requisites":"customer-42","merchant_request_id":"order-10001","preferred_method":"c2c","sub_direction":"payin_simple"}'
TS=$(date +%s)
P="/api/v1/merchant/requests"
IDEM="order-10001"
SIG=$(printf 'v2\n%s\nPOST\n%s\n%s\n%s' "$TS" "$P" "$IDEM" "$BODY" | openssl dgst -sha256 -hmac "YOUR_HMAC_SECRET" | awk '{print $NF}')

curl -s -X POST "https://api.slipstream.cash$P" \
  -H "Authorization: Bearer YOUR_MERCHANT_KEY" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature-Version: 2" \
  -H "X-Signature: $SIG" \
  -H "X-Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" \
  --data "$BODY"

// signedHeaders(), canonical() — see “Authentication”
const path = '/api/v1/merchant/requests';
const body = {
  merchant_request_id: 'order-10001',
  sub_direction: 'payin_simple',
  preferred_method: 'c2c',
  client_amount: '5000.00',
  client_bank: 'tinkoff',
  client_full_name: 'Иван Иванов',
  client_requisites: 'customer-42',
  callback_url: 'https://merchant.example.com/webhook',
};

const res = await fetch('https://api.slipstream.cash' + path, {
  method: 'POST',
  headers: signedHeaders('POST', path, body, body.merchant_request_id), // v2: key is signed
  body: canonical(body),
});
const { success, data, error } = await res.json();
if (!success) throw new Error(error);
if (!data.requisites) { /* no requisite found — see “Requisites & links” */ }

import requests  # signed_headers(), canonical() — see “Authentication”

path = "/api/v1/merchant/requests"
body = {
    "merchant_request_id": "order-10001",
    "sub_direction": "payin_simple",
    "preferred_method": "c2c",
    "client_amount": "5000.00",
    "client_bank": "tinkoff",
    "client_full_name": "Иван Иванов",
    "client_requisites": "customer-42",
    "callback_url": "https://merchant.example.com/webhook",
}
headers = signed_headers("POST", path, body, body["merchant_request_id"])  # v2: key is signed

r = requests.post("https://api.slipstream.cash" + path,
                  data=canonical(body).encode("utf-8"), headers=headers, timeout=30)
resp = r.json()
if not resp["success"]:
    raise RuntimeError(resp["error"])
print(resp["data"]["public_id"], resp["data"].get("requisites"))

Ответ 200

Response 200

{
  "success": true,
  "data": {
    "kind": "payin",
    "public_id": "PI-3f9a1c7e5b2d4a60",
    "merchant_request_id": "order-10001",
    "status": "Working",
    "created_at": "2026-09-23T08:15:02.114Z",
    "rub_amount": "5000.00",
    "usdt_amount": "51.35135135",
    "rate": "92.5000",
    "rate_with_commission": "87.8750",
    "requisites": {
      "method": "c2c",
      "type": "card",
      "card_number": "2200123412341234",
      "phone": null,
      "account": null,
      "bik": null,
      "bank": "tinkoff",
      "bank_name": "Т-Банк",
      "holder": "Иван П.",
      "link": null,
      "payment_url": null,
      "qr_payload": null,
      "expires_at": "2026-09-23T08:35:02.114Z"
    },
    "instant_match": { "attempted": true, "matched": false }
  }
}

04Примеры по методамExamples by method

Тело запроса и типичный ответ для каждого метода. Заголовки и подпись — как в разделе Авторизация.

Request body and a typical response for each method. Headers and signing — as in Authentication.

{
  "merchant_request_id": "order-c2c-1",
  "sub_direction": "payin_simple",
  "preferred_method": "c2c",
  "client_amount": "5000.00",
  "client_bank": "sber",
  "client_full_name": "Иван Иванов",
  "client_requisites": "customer-42",
  "callback_url": "https://merchant.example.com/webhook"
}

{
  "success": true,
  "data": {
    "kind": "payin",
    "public_id": "PI-3f9a1c7e5b2d4a60",
    "merchant_request_id": "order-c2c-1",
    "status": "Working",
    "created_at": "2026-09-23T08:15:02.114Z",
    "rub_amount": "5000.00",
    "usdt_amount": "51.35135135",
    "rate": "92.5000",
    "rate_with_commission": "87.8750",
    "requisites": {
      "method": "c2c",
      "type": "card",
      "card_number": "2200123412341234",
      "phone": null,
      "account": null,
      "bik": null,
      "bank": "sber",
      "bank_name": "Сбер",
      "holder": "Иван П.",
      "link": null,
      "payment_url": null,
      "qr_payload": null,
      "expires_at": "2026-09-23T08:35:02.114Z"
    },
    "instant_match": { "attempted": true, "matched": false }
  }
}

{
  "merchant_request_id": "order-sbp-1",
  "sub_direction": "payin_simple",
  "preferred_method": "sbp",
  "client_amount": "3200.00",
  "client_bank": "any",
  "client_full_name": "Иван Иванов",
  "client_requisites": "customer-42",
  "callback_url": "https://merchant.example.com/webhook"
}

{
  "success": true,
  "data": {
    "kind": "payin",
    "public_id": "PI-8c21d0e94ab37f15",
    "merchant_request_id": "order-sbp-1",
    "status": "Working",
    "created_at": "2026-09-23T08:20:44.901Z",
    "rub_amount": "3200.00",
    "usdt_amount": "32.86486486",
    "rate": "92.5000",
    "rate_with_commission": "87.8750",
    "requisites": {
      "method": "sbp",
      "type": "sbp",
      "card_number": null,
      "phone": "+79001234567",
      "account": null,
      "bik": null,
      "bank": "tinkoff",
      "bank_name": "Т-Банк",
      "holder": "Мария С.",
      "link": null,
      "payment_url": null,
      "qr_payload": null,
      "expires_at": "2026-09-23T08:40:44.901Z"
    },
    "instant_match": { "attempted": true, "matched": false }
  }
}

{
  "merchant_request_id": "order-sbpcheck-1",
  "sub_direction": "payin_check",
  "preferred_method": "sbp_check",
  "client_amount": "7500.00",
  "client_bank": "sber",
  "client_full_name": "Иван Иванов",
  "client_requisites": "customer-42",
  "callback_url": "https://merchant.example.com/webhook"
}

{
  "success": true,
  "data": {
    "kind": "payin",
    "public_id": "PI-5e0b7a3c91f24d88",
    "merchant_request_id": "order-sbpcheck-1",
    "status": "Working",
    "created_at": "2026-09-23T08:31:10.377Z",
    "rub_amount": "7500.00",
    "usdt_amount": "77.02702702",
    "rate": "92.5000",
    "rate_with_commission": "87.8750",
    "requisites": {
      "method": "sbp_check",
      "type": "sbp",
      "card_number": null,
      "phone": "+79007654321",
      "account": null,
      "bik": null,
      "bank": "sber",
      "bank_name": "Сбербанк",
      "holder": "Алексей К.",
      "link": null,
      "payment_url": null,
      "qr_payload": null,
      "expires_at": "2026-09-23T08:51:10.377Z"
    },
    "instant_match": { "attempted": true, "matched": false }
  }
}

{
  "merchant_request_id": "order-dl-sbp-1",
  "sub_direction": "payin_simple",
  "preferred_method": "deeplink_sbp",
  "client_amount": "2500.00",
  "client_bank": "any",
  "client_requisites": "customer-42",
  "callback_url": "https://merchant.example.com/webhook"
}

{
  "success": true,
  "data": {
    "kind": "payin",
    "public_id": "PI-a7d44e1f0c9b2356",
    "merchant_request_id": "order-dl-sbp-1",
    "status": "Working",
    "created_at": "2026-09-23T08:40:05.012Z",
    "rub_amount": "2500.00",
    "usdt_amount": "25.67567567",
    "rate": "92.5000",
    "rate_with_commission": "87.8750",
    "requisites": {
      "method": "deeplink_sbp",
      "type": "link",
      "card_number": null,
      "phone": null,
      "account": null,
      "bik": null,
      "bank": null,
      "bank_name": null,
      "holder": null,
      "link": "https://pay.example.com/f/9Qx2LmA7",
      "payment_url": "https://pay.example.com/f/9Qx2LmA7",
      "qr_payload": null,
      "expires_at": "2026-09-23T09:00:05.012Z"
    },
    "instant_match": { "attempted": true, "matched": false }
  }
}

{
  "merchant_request_id": "order-dl-card-1",
  "sub_direction": "payin_simple",
  "preferred_method": "deeplink_card",
  "client_amount": "4100.00",
  "client_bank": "any",
  "client_requisites": "customer-42",
  "callback_url": "https://merchant.example.com/webhook"
}

{
  "success": true,
  "data": {
    "kind": "payin",
    "public_id": "PI-2b9f60c3d815ea47",
    "merchant_request_id": "order-dl-card-1",
    "status": "Working",
    "created_at": "2026-09-23T08:44:51.640Z",
    "rub_amount": "4100.00",
    "usdt_amount": "42.10810810",
    "rate": "92.5000",
    "rate_with_commission": "87.8750",
    "requisites": {
      "method": "deeplink_card",
      "type": "link",
      "card_number": null,
      "phone": null,
      "account": null,
      "bik": null,
      "bank": null,
      "bank_name": null,
      "holder": null,
      "link": "https://pay.example.com/f/Hk3vT0pZ",
      "payment_url": "https://pay.example.com/f/Hk3vT0pZ",
      "qr_payload": null,
      "expires_at": "2026-09-23T09:04:51.640Z"
    },
    "instant_match": { "attempted": true, "matched": false }
  }
}

05Методы оплатыPayment methods

Метод передаётся в preferred_method. Использовать можно только методы, подключённые вашему аккаунту — список и текущие суммы смотрите в GET /limits.

The method is passed in preferred_method. Only methods enabled for your account can be used — see the list and current amounts via GET /limits.

* Телефон всегда приходит в phone в формате +7XXXXXXXXXX. sim, account, nspk, viet_qr, cross_border подключаются по запросу.

* The phone always arrives in phone, formatted +7XXXXXXXXXX. sim, account, nspk, viet_qr, cross_border are enabled on request.

Алиасы

Aliases

Для совместимости с интеграциями предыдущей версии Slipstream принимаются имена (регистр не важен):

For compatibility with previous Slipstream integrations the following names are accepted (case-insensitive):

06Реквизиты и ссылкиRequisites & links

Реквизиты для оплаты приходят в объекте requisites — в ответе на создание заявки и в GET /payin/{public_id}, пока заявка открыта. Формат один и тот же для всех методов.

Payment requisites come in the requisites object — in the create response and in GET /payin/{public_id} while the request is open. The format is the same for all methods.

Повторно получить реквизиты можно через GET /payin/{public_id} — пока заявка открыта (Waiting/Working/Processing) и реквизит выдан. После Confirmed/Canceled там requisites: null. Если потерялся ответ на создание, можно также повторить тот же POST /requests с тем же X-Idempotency-Key и телом (см. Идемпотентность).

Requisites can be re-fetched via GET /payin/{public_id} while the request is open (Waiting/Working/Processing) and a requisite has been issued. After Confirmed/Canceled it returns requisites: null. If the create response was lost you can also repeat the same POST /requests with the same X-Idempotency-Key and body (see Idempotency).

07Чеки (proof)Receipts (proof)

Приложить чек об оплате к заявке. Для sbp_check и card_check — обязательно (только PDF); для остальных методов — по желанию, помогает при спорных платежах.

Attach a payment receipt to a request. Mandatory for sbp_check and card_check (PDF only); optional for other methods — helps with disputed payments.

Вариант 1 — JSON (base64)

Option 1 — JSON (base64)

{
  "public_id": "PI-5e0b7a3c91f24d88",
  "file_name": "receipt.pdf",
  "mime_type": "application/pdf",
  "file_base64": "JVBERi0xLjQKJcfsj6IK...",
  "note": "order-sbpcheck-1"
}

{
  "success": true,
  "data": {
    "proof_id": "1842",
    "public_id": "PI-5e0b7a3c91f24d88",
    "status": "pending",
    "file_name": "receipt.pdf",
    "file_size": 48213,
    "created_at": "2026-09-23T08:36:12.508Z",
    "forwarded": true
  }
}

Вариант 2 — multipart/form-data

Option 2 — multipart/form-data

Файлы — в поле receipts (до 5 файлов по 10 МБ), public_id — полем формы или в query ?public_id=, опционально note. Подпись для multipart считается от тела {}.

Files go into the receipts field (up to 5 files × 10 MB), public_id — as a form field or ?public_id= query, optional note. The signature for multipart is computed over the body {}.

TS=$(date +%s)
P="/api/v1/merchant/payin/proof"
KEY="proof-PI-5e0b7a3c91f24d88-1"
# v2: "v2\n{ts}\nPOST\n{path}\n{idempotency_key}\n{}" (multipart body is always {})
SIG=$(printf 'v2\n%s\nPOST\n%s\n%s\n{}' "$TS" "$P" "$KEY" | openssl dgst -sha256 -hmac "YOUR_HMAC_SECRET" | awk '{print $NF}')

curl -s -X POST "https://api.slipstream.cash$P" \
  -H "Authorization: Bearer YOUR_MERCHANT_KEY" \
  -H "X-Timestamp: $TS" -H "X-Signature-Version: 2" -H "X-Signature: $SIG" \
  -H "X-Idempotency-Key: $KEY" \
  -F "public_id=PI-5e0b7a3c91f24d88" \
  -F "receipts=@receipt.pdf;type=application/pdf"

{
  "success": true,
  "data": {
    "attached": 1,
    "receipts": [ { "id": "1843", "filename": "receipt.pdf" } ],
    "public_id": "PI-5e0b7a3c91f24d88",
    "forwarded": true
  }
}

Правила и ответы

Rules and responses

• Для sbp_check / card_check принимается только PDF, файл проверяется по сигнатуре %PDF — переименованная картинка вернёт 400.
• For sbp_check / card_check PDF only is accepted; the file is checked for the %PDF signature — a renamed image returns 400.
• Чек можно приложить в любом статусе, кроме Canceled (→ 409, в т.ч. для истёкшей заявки). Можно отправить несколько чеков — до 10 на заявку (больше → 409 Too many receipts for this request); повторная отправка того же файла лимит не расходует.
• A receipt can be attached in any status except Canceled (→ 409, including expired requests). Multiple receipts are allowed — up to 10 per request (more → 409 Too many receipts for this request); re-sending the same file does not count against the limit.
• forwarded: true — чек передан на проверку платежа и принят; null — дополнительная передача не требуется, чек сохранён для проверки.
• forwarded: true — the receipt was passed on for payment verification and accepted; null — no further forwarding needed, the receipt is stored for review.
• 424 — чек сохранён, но не принят на проверку (причина — в error). Исправьте файл или повторите отправку того же файла с новым X-Idempotency-Key — повторно он не сохраняется.
• 424 — the receipt is saved but was not accepted for verification (reason in error). Fix the file, or resend the same file with a new X-Idempotency-Key — it is not stored twice.
• Сам по себе чек не подтверждает платёж: решение принимается после проверки поступления, результат придёт вебхуком.
• A receipt alone does not confirm the payment: the decision is made after the incoming payment is verified, the result arrives by webhook.

{
  "success": false,
  "error": "Receipts were saved on our side, but were not accepted on verification. Check the file and retry with a new idempotency key.",
  "attached": 1,
  "receipts": [ { "id": "1844", "filename": "receipt.pdf" } ]
}

08Статус заявкиRequest status

GET подписывается от тела {}; путь для подписи — с public_id, например /api/v1/merchant/payin/PI-3f9a1c7e5b2d4a60. Чужая заявка или не то направление → 404.

GET is signed over the body {}; the signed path includes public_id, e.g. /api/v1/merchant/payin/PI-3f9a1c7e5b2d4a60. Someone else's request or the wrong direction → 404.

{
  "success": true,
  "data": {
    "public_id": "PI-3f9a1c7e5b2d4a60",
    "status": "Working",
    "rub_amount": "5000.00",
    "actual_amount": null,
    "amount_mismatch": false,
    "usdt_amount": "51.35135135",
    "rate": "92.5000",
    "rate_with_commission": "87.8750",
    "requisites": {
      "method": "c2c",
      "type": "card",
      "card_number": "2200123412341234",
      "phone": null,
      "account": null,
      "bik": null,
      "bank": "tinkoff",
      "bank_name": "Т-Банк",
      "holder": "Иван П.",
      "link": null,
      "payment_url": null,
      "expires_at": "2026-09-23T08:35:02.114Z"
    },
    "expires_at": "2026-09-23T08:35:02.114Z",
    "linked_requests": []
  }
}

{
  "success": true,
  "data": {
    "public_id": "PI-3f9a1c7e5b2d4a60",
    "status": "Confirmed",
    "rub_amount": "5000.00",
    "actual_amount": "4700.00",
    "amount_mismatch": true,
    "usdt_amount": "51.35135135",
    "rate": "92.5000",
    "rate_with_commission": "87.8750",
    "requisites": null,
    "expires_at": null,
    "linked_requests": []
  }
}

Ответ для payout — public_id, status, rub_amount, actual_amount, amount_mismatch, usdt_amount, rate, rate_with_commission (без requisites, expires_at и linked_requests).

The payout response has public_id, status, rub_amount, actual_amount, amount_mismatch, usdt_amount, rate, rate_with_commission (no requisites, expires_at or linked_requests).

Статусы

Statuses

(Processing) ──► Waiting ──► Working ──► Confirmed ──(reversal)──► Canceled
                    │           │
                    └───────────┴──► Canceled ──(late confirm / dispute)──► Confirmed

09ОтменаCancel

Отменить payin, пока он в статусе Waiting или Working. Отмена payout через API не поддерживается.

Cancel a payin while it is Waiting or Working. Payout cancellation via API is not supported.

{ "public_id": "PI-3f9a1c7e5b2d4a60" }

{ "success": true, "data": { "public_id": "PI-3f9a1c7e5b2d4a60", "status": "Canceled" } }

• Заявка в финальном статусе → 409 Cannot cancel request in terminal status Confirmed (или Canceled).
• Request in a final status → 409 Cannot cancel request in terminal status Confirmed (or Canceled).
• Статус изменился в момент отмены или заявка в Processing → 409 Request state changed, cannot cancel — запросите статус.
• Status changed during cancellation, or the request is Processing → 409 Request state changed, cannot cancel — query the status.
• После успешной отмены на callback_url приходит вебхук Canceled, реквизит освобождается.
• After a successful cancel a Canceled webhook is sent to callback_url, the requisite is released.

10Выплаты (payout)Payouts

Выплата создаётся тем же POST /requests с sub_direction вида payout_*. Реквизит получателя — в client_requisites (+ client_additional_requisites).

A payout is created with the same POST /requests using a payout_* sub_direction. The recipient requisite goes into client_requisites (+ client_additional_requisites).

{
  "merchant_request_id": "payout-777",
  "sub_direction": "payout_check",
  "preferred_method": "c2c",
  "client_amount": "12000.00",
  "client_bank": "sber",
  "client_requisites": "2200123412341234",
  "client_additional_requisites": "Иван Иванов",
  "client_full_name": "Иван Иванов",
  "callback_url": "https://merchant.example.com/webhook"
}

{
  "success": true,
  "data": {
    "kind": "payout",
    "public_id": "PO-1d7c9e20ab45f318",
    "merchant_request_id": "payout-777",
    "status": "Working",
    "created_at": "2026-09-23T09:02:17.221Z",
    "rub_amount": "12000.00",
    "usdt_amount": "127.13513514",
    "rate": "92.5000",
    "rate_with_commission": "90.6500",
    "instant_match": { "attempted": true, "matched": false }
  }
}

requisites для payout не возвращаются. Working — выплата принята в работу, Waiting — ещё ожидает назначения. Итог приходит вебхуком payout.status.changed; статус — GET /payout/{public_id}. В примере комиссия на выплату — 2%. Выплата создаётся только в пределах доступного баланса аккаунта (баланс минус открытые выплаты), иначе — 409 Insufficient merchant balance for payout: ….

requisites are not returned for payouts. Working — the payout is in progress, Waiting — awaiting assignment. The outcome arrives via the payout.status.changed webhook; status — GET /payout/{public_id}. The example assumes a 2% payout commission. A payout is accepted only within your available balance (balance minus open payouts), otherwise — 409 Insufficient merchant balance for payout: ….

11ВебхукиWebhooks

Slipstream отправляет POST на callback_url заявки, когда payin получил реквизит и когда заявка переходит в финальный статус.

Slipstream sends a POST to the request's callback_url when a payin gets its requisite and when the request reaches a final status.

Прочие промежуточные переходы (Waiting → Working) отдельным вебхуком не отправляются. Порядок доставки разных событий не гарантирован: ориентируйтесь на поле event и не откатывайте финальный статус назад по более позднему payin.requisites.issued.

Other intermediate transitions (Waiting → Working) are not sent as separate webhooks. Delivery order across events is not guaranteed: rely on the event field and never roll a final status back because of a later payin.requisites.issued.

Заголовки

Headers

POST /webhook HTTP/1.1
Content-Type: application/json
X-Event: payin.status.changed
X-Delivery-Id: 9b2f6c1e-4d7a-4f0e-9a51-2c8e7d3b1f60
X-Timestamp: 1790154137
X-Signature-V2: 5e0c…a41f
X-Signature: 3b6f…e91a

Тело: payin.requisites.issued

Body: payin.requisites.issued

{
  "event": "payin.requisites.issued",
  "public_id": "PI-3f9a1c7e5b2d4a60",
  "merchant_request_id": "order-10001",
  "status": "Working",
  "kind": "payin",
  "method": "c2c",
  "rub_amount": "5000.00",
  "requisites": {
    "method": "c2c",
    "type": "card",
    "card_number": "2200123412341234",
    "phone": null,
    "account": null,
    "bik": null,
    "bank": "sber",
    "bank_name": "Сбербанк",
    "holder": "Иван И.",
    "link": null,
    "payment_url": null,
    "expires_at": "2026-09-23T09:17:17.221Z"
  },
  "expires_at": "2026-09-23T09:17:17.221Z",
  "sent_at": "2026-09-23T09:02:18.004Z"
}

Тело: payin.status.changed / payout.status.changed

Body: payin.status.changed / payout.status.changed

{
  "event": "payin.status.changed",
  "public_id": "PI-3f9a1c7e5b2d4a60",
  "status": "Confirmed",
  "merchant_request_id": "order-10001",
  "kind": "payin",
  "method": "c2c",
  "rub_amount": "5000.00",
  "actual_amount": "4900.00",
  "amount_mismatch": true,
  "completed_at": "2026-09-23T09:10:41.512Z",
  "canceled_at": null,
  "sent_at": "2026-09-23T09:10:41.873Z"
}

{
  "event": "payout.status.changed",
  "public_id": "PO-1d7c9e20ab45f318",
  "status": "Canceled",
  "merchant_request_id": "payout-777",
  "kind": "payout",
  "method": "c2c",
  "rub_amount": "12000.00",
  "actual_amount": null,
  "amount_mismatch": false,
  "completed_at": null,
  "canceled_at": "2026-09-23T09:20:05.030Z",
  "sent_at": "2026-09-23T09:20:05.311Z"
}

Тело: test

Body: test

{
  "event": "test",
  "merchant_id": "42",
  "ts": "2026-09-23T09:00:00.000Z",
  "sent_at": "2026-09-23T09:00:00.000Z"
}

Проверка подписи

Signature verification

X-Signature-V2 = hex( HMAC_SHA256( YOUR_HMAC_SECRET, X-Timestamp + "." + raw_body ) )
X-Signature    = hex( HMAC_SHA256( YOUR_HMAC_SECRET, raw_body ) )   // переходный период / transition period

Тело отправляется уже в каноническом виде (ключи отсортированы, без пробелов), поэтому проверяйте подпись по сырому телу запроса как есть — до парсинга JSON. Алгоритм проверки: (1) |now − X-Timestamp| ≤ 300 секунд, иначе отклонить — это защита от повторного воспроизведения; (2) посчитать HMAC от X-Timestamp + "." + raw_body и сравнить с X-Signature-V2 в константное время; (3) дедуплицировать по X-Delivery-Id. Часы сервера синхронизируйте по NTP.

The body is already sent in canonical form (sorted keys, no whitespace), so verify the signature over the raw request body as-is — before parsing JSON. Verification: (1) |now − X-Timestamp| ≤ 300 seconds, otherwise reject — this is replay protection; (2) compute HMAC over X-Timestamp + "." + raw_body and compare with X-Signature-V2 in constant time; (3) deduplicate by X-Delivery-Id. Keep your server clock NTP-synced.

const crypto = require('crypto');
const express = require('express');
const app = express();
const SECRET = 'YOUR_HMAC_SECRET';
const WINDOW_SEC = 300;

// raw body: the signature is computed over the exact bytes we sent
app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  const raw = req.body.toString('utf8');
  const ts = Number(req.get('X-Timestamp'));
  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > WINDOW_SEC) {
    return res.status(401).end(); // stale or missing timestamp — possible replay
  }
  const expected = Buffer.from(crypto.createHmac('sha256', SECRET)
    .update(`${ts}.${raw}`, 'utf8').digest('hex'));
  const got = Buffer.from(String(req.get('X-Signature-V2') || ''));
  if (got.length !== expected.length || !crypto.timingSafeEqual(got, expected)) {
    return res.status(401).end();
  }

  const deliveryId = req.get('X-Delivery-Id');
  if (await alreadyProcessed(deliveryId)) return res.status(200).json({ ok: true });

  const body = JSON.parse(raw);
  switch (body.event) {
    case 'payin.requisites.issued': await showRequisites(body.merchant_request_id, body.requisites); break;
    case 'payin.status.changed':
    case 'payout.status.changed':  await applyStatus(body.merchant_request_id, body.public_id, body.status, body.actual_amount); break;
  }
  await markProcessed(deliveryId);
  res.status(200).json({ ok: true });
});

import hashlib, hmac, json, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = b"YOUR_HMAC_SECRET"
WINDOW_SEC = 300

@app.post("/webhook")
def webhook():
    raw = request.get_data()  # exact bytes as sent
    try:
        ts = int(request.headers.get("X-Timestamp", ""))
    except ValueError:
        abort(401)
    if abs(time.time() - ts) > WINDOW_SEC:
        abort(401)  # stale timestamp — possible replay
    expected = hmac.new(SECRET, f"{ts}.".encode() + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-Signature-V2", "")):
        abort(401)

    delivery_id = request.headers.get("X-Delivery-Id")
    if already_processed(delivery_id):
        return {"ok": True}, 200

    body = json.loads(raw)
    if body["event"] == "payin.requisites.issued":
        show_requisites(body.get("merchant_request_id"), body["requisites"])
    elif body["event"] in ("payin.status.changed", "payout.status.changed"):
        apply_status(body.get("merchant_request_id"), body["public_id"], body["status"], body.get("actual_amount"))
    mark_processed(delivery_id)
    return {"ok": True}, 200

Доставка и повторы

Delivery and retries

• Успех — любой HTTP-ответ 2xx в течение 10 секунд. Всё остальное (другой код, таймаут, ошибка соединения) — повтор.
• Success — any 2xx HTTP response within 10 seconds. Anything else (other code, timeout, connection error) triggers a retry.
• Всего до 5 попыток: сразу, затем примерно через 5 с, 30 с, 5 мин и 1 ч. После пятой неудачи доставка прекращается — сверяйте статус через GET /payin/{public_id}.
• Up to 5 attempts in total: immediately, then after roughly 5 s, 30 s, 5 min and 1 h. After the fifth failure delivery stops — reconcile via GET /payin/{public_id}.
• У всех повторов одной доставки одинаковые тело (кроме sent_at) и X-Delivery-Id; X-Timestamp и подпись — свежие на каждую попытку.
• All retries of one delivery share the body (except sent_at) and X-Delivery-Id; X-Timestamp and the signature are fresh on every attempt.
• Финальный вебхук записывается атомарно со сменой статуса и не теряется при сбоях на нашей стороне. Повторную отправку можно запустить вручную из кабинета мерчанта (с тем же X-Delivery-Id).
• The final webhook is recorded atomically with the status change and is not lost on failures on our side. A resend can be triggered manually from the merchant cabinet (with the same X-Delivery-Id).

12ИдемпотентностьIdempotency

Все POST требуют X-Idempotency-Key — защита от двойного создания заявки при повторах и сетевых сбоях.

Every POST requires X-Idempotency-Key — protection against duplicate requests on retries and network failures.

• Ключ уникален в рамках вашего аккаунта. Тело сравнивается канонически — порядок ключей не важен.
• The key is scoped to your account. Bodies are compared canonically — key order does not matter.
• Ответы 4xx тоже сохраняются: исправив тело, используйте новый ключ.
• 4xx responses are stored too: after fixing the body, use a new key.
• Если получили 5xx или таймаут, повтор с тем же ключом может вернуть 409: первый запрос мог быть выполнен. Если в теле есть merchant_request_id, через ~10 минут повтор с тем же ключом и телом выполнится заново — безопасно, т.к. дубль по merchant_request_id вернёт 409 с public_id уже созданной заявки. Без merchant_request_id не создавайте новую заявку вслепую — сверьтесь с кабинетом или поддержкой.
• If you got a 5xx or a timeout, retrying with the same key may return 409: the first request may have been executed. If the body has a merchant_request_id, after ~10 minutes a retry with the same key and body is executed again — safe, because a duplicate merchant_request_id returns 409 with the existing public_id. Without merchant_request_id, do not blindly create a new request — check the cabinet or contact support.

13ЛимитыLimits

Актуальные min/max суммы по каждому методу для вашего аккаунта — считаются по реквизитам, которые прямо сейчас могут принять заявку. Значения меняются в течение дня: опрашивайте периодически (например, раз в минуту) и не показывайте покупателю методы с available: false.

Current min/max amounts per method for your account, computed from requisites that can accept a request right now. Values change during the day: poll periodically (e.g. once a minute) and hide methods with available: false from customers.

{
  "success": true,
  "data": {
    "currency": "RUB",
    "updatedAt": "2026-09-23T09:10:00.000Z",
    "methods": [
      { "code": "c2c", "label": "К2К", "available": true, "sources": 4,
        "min": 100000, "max": 15000000, "minRub": 1000, "maxRub": 150000 },
      { "code": "sbp", "label": "СБП", "available": true, "sources": 2,
        "min": 50000, "max": 50000000, "minRub": 500, "maxRub": 500000 },
      { "code": "deeplink_card", "label": "Deeplink Карта", "available": false, "sources": 0,
        "min": null, "max": null, "minRub": null, "maxRub": null }
    ]
  }
}

В список входят все включённые в системе методы; неподключённые вам отдаются с available: false.

The list contains all methods enabled in the system; those not enabled for you come with available: false.

Технические лимиты API

Technical API limits

14ДиспутыDisputes

Покупатель утверждает, что оплатил, а заявка не подтверждена? Откройте диспут; пока заявка не в Canceled, приложите чек через POST /payin/proof к той же заявке. К заявке в статусе Canceled чек через API не прикрепить (409) — укажите в reason сумму, время и банк платежа и передайте чек менеджеру.

The customer says they paid but the request isn't confirmed? Open a dispute; while the request is not Canceled, attach the receipt via POST /payin/proof to the same request. A receipt cannot be attached via API to a Canceled request (409) — put the payment amount, time and bank in reason and send the receipt to your manager.

{ "public_id": "PI-3f9a1c7e5b2d4a60", "reason": "Клиент оплатил 5000 ₽ в 11:42, чек приложен" }

{
  "success": true,
  "data": {
    "dispute_id": "57",
    "public_id": "PI-3f9a1c7e5b2d4a60",
    "status": "open",
    "kind": "payment",
    "reason": "Клиент оплатил 5000 ₽ в 11:42, чек приложен",
    "note": null,
    "resolved_at": null,
    "deadline_at": "2026-10-07T09:20:00.000Z",
    "created_at": "2026-09-23T09:20:00.000Z"
  }
}

• reason — от 3 до 2000 символов. Срок рассмотрения — 14 дней (deadline_at).
• reason — 3 to 2000 chars. Review deadline — 14 days (deadline_at).
• Статусы: open → (in_progress) → won или rejected. kind: "payment" — спор по неподтверждённой заявке: won = платёж признан, придёт вебхук Confirmed. kind: "chargeback" — спор по уже подтверждённой заявке: won = оплата отменена, придёт вебхук Canceled с reversed: true. Об изменении статуса спора вебхук не приходит — опрашивайте GET /disputes/{dispute_id}.
• Statuses: open → (in_progress) → won or rejected. kind: "payment" — dispute on an unconfirmed request: won = payment accepted, a Confirmed webhook follows. kind: "chargeback" — dispute on an already confirmed request: won = payment reversed, a Canceled webhook with reversed: true follows. No webhook is sent on dispute status changes — poll GET /disputes/{dispute_id}.
• По заявке, оплата которой уже отменена (сторно), диспут не открыть (409); на заявку может быть только один активный диспут (409).
• No dispute on a request whose payment has already been reversed (409); only one active dispute per request (409).

15Коды ошибокError codes

Формат ошибки единый. Для ошибок валидации дополнительно приходит массив errors вида "поле: сообщение".

The error format is uniform. Validation errors additionally include an errors array of "field: message".

{
  "success": false,
  "error": "client_amount: client_amount must be a positive decimal string",
  "errors": [
    "client_amount: client_amount must be a positive decimal string"
  ]
}

16Справочник банковBank reference

Коды для client_bank. Регистр не важен. any — любой банк. Список может расширяться; неизвестный код не вызывает ошибку, но может сузить подбор реквизита.

Codes for client_bank. Case-insensitive. any — any bank. The list may grow; an unknown code does not raise an error but may narrow requisite selection.

Коды sim_* — только для метода sim.

sim_* codes are for the sim method only.

17FAQ