От запроса
до оплаченного заказа.

Создайте платёж на своём сервере, откройте покупателю ссылку и получите подтверждение через подписанный вебхук.

1. Подготовьте магазин

   Менеджер подключает магазин и способы оплаты. В кабинете откройте «Ещё → Интеграция», выпустите ключ с нужными правами и сохраните секрет на сервере. Он выдаётся один раз.

2. Создайте платёж

   Отправьте подписанный POST с постоянным ключом идемпотентности для этой операции. Сохраните ID платежа рядом с заказом и передайте покупателю checkout_url.

3. Подтвердите результат

   Проверьте подпись вебхука и сопоставьте платёж с заказом. Переход покупателя обратно на ваш сайт не является доказательством оплаты.

Подпись каждого запроса

API предназначен для запросов с вашего backend. Секрет нельзя встраивать в браузер, приложение покупателя или URL. Тело POST передаётся как UTF-8 JSON с Content-Type: application/json.

METHOD
/api/v1/path?query=value
TIMESTAMP
NONCE
SHA256_HEX_OF_EXACT_BODY

Разделитель строк: \n. Метод в верхнем регистре, путь включает исходную query string. Для GET хешируется пустая строка. Сначала сформируйте байты тела, затем подпишите и отправьте именно их.

import { createHash, createHmac, randomBytes } from "node:crypto";

const keyId = process.env.SHIFTPAY_KEY_ID;
const secret = process.env.SHIFTPAY_API_SECRET;
if (!keyId || !secret) throw new Error("Configure server-side API credentials");
const apiOrigin = process.env.SHIFTPAY_API_BASE || "https://api.shiftpay.cc";
if (!apiOrigin) throw new Error("Configure SHIFTPAY_API_BASE with your API origin");
const method = "GET";
const path = "/api/v1/payments?limit=1";
const body = "";
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = randomBytes(24).toString("hex");
const digest = createHash("sha256").update(body).digest("hex");
const canonical = [method, path, timestamp, nonce, digest].join("\n");
const signature = createHmac("sha256", secret).update(canonical).digest("hex");
const response = await fetch(new URL(path, apiOrigin), {
  method, redirect: "error", signal: AbortSignal.timeout(15000),
  headers: {
    "X-Project-Id": "YOUR_PROJECT_ID",
    "X-Key-Id": keyId, "X-Timestamp": timestamp,
    "X-Nonce": nonce, "X-Signature": "v1=" + signature
  }
});
console.log("HTTP status:", response.status);

Создание платёжной ссылки

Сумма задаётся строкой. Комиссия и доля покупателя берутся из условий магазина; их нельзя переопределить произвольными полями в запросе. Не указывайте method, если способ выбирает покупатель.

{
  "amount": "100.00",
  "currency": "RUB",
  "merchant_order_id": "YOUR_ORDER_ID",
  "description": "Оплата заказа"
}

import { createHash, createHmac, randomBytes } from "node:crypto";

const { SHIFTPAY_PROJECT_ID: projectId, SHIFTPAY_KEY_ID: keyId,
  SHIFTPAY_API_SECRET: secret, SHIFTPAY_ORDER_ID: orderId,
  SHIFTPAY_IDEMPOTENCY_KEY: idempotencyKey } = process.env;
if (!projectId || !keyId || !secret || !orderId || !idempotencyKey)
  throw new Error("Configure credentials, order ID and a persistent idempotency key");

const path = "/api/v1/payments";
const body = JSON.stringify({ amount: "100.00", currency: "RUB",
  merchant_order_id: orderId, description: "Order payment" });
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = randomBytes(24).toString("hex");
const digest = createHash("sha256").update(body).digest("hex");
const canonical = ["POST", path, timestamp, nonce, digest].join("\n");
const signature = createHmac("sha256", secret).update(canonical).digest("hex");
const response = await fetch("https://api.shiftpay.cc" + path, {
  method: "POST", redirect: "error", signal: AbortSignal.timeout(15000),
  headers: { "Content-Type": "application/json", "X-Project-Id": projectId,
    "X-Key-Id": keyId, "X-Timestamp": timestamp, "X-Nonce": nonce,
    "X-Signature": "v1=" + signature, "Idempotency-Key": idempotencyKey },
  body,
});
if (!response.ok) {
  const problem = await response.json();
  throw new Error("HTTP " + response.status + ": " + problem.code);
}
const payment = await response.json();
// Store payment.id with your order. Redirect the buyer to payment.checkout_url.
// The order is not paid just because a checkout link was created. Record payment
// only after a verified payment.succeeded event and reconciliation with GET.

Ответ 201

Ответ содержит id, status, checkout_url, amount, currency, payer_total, merchant_amount, fee, merchant_order_id, expires_at и livemode. Ссылка живёт до expires_at. Создание ссылки не означает оплату или готовность всех провайдеров.

Когда заказ оплачен

Используйте GET /payments/{id} для актуального состояния. Событие успешного завершения: payment.succeeded, статус платежа: paid.

awaiting_method / pending

Выбор способа или ожидание оплаты.

detected / confirming

Поступление обнаружено, подтверждение или распределение ещё не закончено. Не выдавайте заказ как оплаченный.

paid

Оплата завершена в учёте. Деньги могут оставаться в hold или reserve; доступную сумму проверяйте через /balance.

underpaid / overpaid / manual_review / aml_hold

Требуется дополнительная обработка. Не приравнивайте эти состояния к paid.

expired / cancelled / failed

Срок истёк, платёж отменён или завершился ошибкой.

refund_pending / refunded

Возврат ожидает завершения или завершён.

Методы API

Все пути ниже относительно базового адреса. Доступ ограничен магазином и средой ключа. Финансовые операции дополнительно проверяют права владельца ключа и условия магазина.

Приём вебхуков

В кабинете «Интеграция» задайте HTTPS-адрес обработчика, сохраните отдельный секрет вебхуков и активируйте адрес до создания платежей. События, созданные до подключения обработчика, автоматически не досылаются.

Доставка выполняется как минимум один раз: возможны повторы и иной порядок событий. Заголовки ShiftPay-Event-ID и ShiftPay-Event идентифицируют событие; ShiftPay-Timestamp содержит Unix time; ShiftPay-Signature содержит v1=HMAC-SHA256(secret, timestamp + "." + raw_body).

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody is a Buffer containing the ORIGINAL request bytes, before JSON parsing.
// headers is a Headers object. Use the webhook secret, not the API key secret.
export function verifyWebhook(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== "string" || !secret) return false;
  const timestamp = headers.get("ShiftPay-Timestamp") ?? "";
  const signature = headers.get("ShiftPay-Signature") ?? "";
  if (!/^\d{10}$/.test(timestamp) || !/^v1=[a-fA-F0-9]{64}$/.test(signature))
    return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > 300)
    return false;
  const expected = createHmac("sha256", secret)
    .update(timestamp + ".").update(rawBody).digest();
  const received = Buffer.from(signature.slice(3), "hex");
  return received.length === expected.length && timingSafeEqual(received, expected);
}
// After verification, parse JSON and reconcile the event with your stored order.
// Deduplicate ShiftPay-Event-ID durably in the same transaction as the order update.
// Respond with 2xx only after that transaction commits. Replays must be harmless.

После проверки подписи сопоставьте платёж, магазин, валюту и сумму с вашим заказом. Сохраняйте обработанный ID события и изменение заказа атомарно. Повтор уже обработанного события должен безопасно возвращать 2xx, без повторной выдачи товара.

Ошибки и безопасные повторы

Ошибки возвращаются как application/problem+json с HTTP-статусом и полем code. Для обращения в поддержку сохраните X-Correlation-Id и идентификатор запроса из ответа. Не отправляйте секреты или подписи.

400 / 415 / 422

Проверьте формат JSON, строковую сумму, Content-Type, поля и доступность метода.

401

Проверьте ключ, часы сервера, исходные байты тела и путь. nonce_reused требует нового nonce и подписи, но не нового ключа идемпотентности.

403 / 404

Проверьте права, активность магазина и принадлежность объекта. Чужие платежи недоступны.

409

Конфликт состояния или другая команда под тем же ключом идемпотентности. Сначала прочитайте состояние заказа.

429

Снизьте частоту. Текущий лимит: 180 аутентифицированных запросов в минуту на ключ. Учитывайте Retry-After.

501 / 503

Операция ещё недоступна, не настроена или сервис временно недоступен. live_not_enabled означает, что боевой режим не включён.