Разработчикам
Три запроса и вебхук.
Gateway — это hosted checkout, поэтому интеграция намеренно небольшая: создайте заказ, отправьте клиента на страницу, проверьте подписанный результат. Это весь ваш объём работы — платёжный интерфейс, логику способов оплаты, 3-D Secure, кошельки и чеки мы создаём и поддерживаем в актуальном состоянии сами.
Устройство
С чем вы интегрируетесь.
- REST поверх HTTPS
- JSON на входе, JSON на выходе
- API-ключи Bearer
- Ключи идемпотентности
- Подписанные вебхуки
- Защита от повторной отправки
- Тестовый и боевой режимы
- SDK для iOS и Android
- Плагины для магазинов
- Встраиваемые поля
Быстрый старт
От нуля до оплаченного заказа.
Весь happy path. Суммы указаны в минорных единицах, референсы ваши, а checkout URL — адрес, на который вы перенаправляете клиента. Базовый URL API выдаётся вместе с ключами sandbox — экспортируйте его как PROTOCORE_API_BASE, и приведённые ниже запросы заработают как есть.
Создайте заказ
Один запрос с суммой, валютой и вашим референсом. Ключ идемпотентности генерируете вы — повторный запрос вернёт исходный заказ, а не создаст второй.
curl -X POST "$PROTOCORE_API_BASE/v1/orders" \
-H "Authorization: Bearer $PROTOCORE_API_KEY" \
-H "Idempotency-Key: 9F21-0716" \
-H "Content-Type: application/json" \
-d '{
"amount": 4900,
"currency": "EUR",
"reference": "9F21-0716",
"line_items": [
{ "name": "Brand identity sprint", "amount": 3850 },
{ "name": "Typeface licensing", "amount": 600 },
{ "name": "Rush delivery", "amount": 400 }
],
"return_url": "https://arcstudio.ro/thanks"
}'Отправьте клиента на checkout
В ответе приходит checkout URL на вашем хосте чекаута — выданном вместе с sandbox или на вашем домене, когда вы направите его на нас. Перенаправьте клиента на него или откройте в SDK: на этой странице находятся способы оплаты, кошельки и 3-D Secure, так что вам ничего не нужно разрабатывать.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Проверьте подписанный результат
Когда платёж завершится, на ваш endpoint придёт подписанное событие. Прежде чем чему-либо доверять, проверьте подпись по секрету вебхука, а затем выполняйте заказ по уже известному вам референсу.
{
"type": "order.paid",
"id": "evt_7Ka2Lm",
"created": "2026-07-23T09:41:02Z",
"data": {
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"method": "usdc",
"settlement": { "currency": "EUR", "amount": 4900, "rate": "0.9184" }
}
}Справочник
Эндпоинты, которые пригодятся на практике.
В документации есть и другое, но большинство интеграций не выходит за пределы этого набора.
Вебхуки
О чём узнаёт ваш бэкенд.
Каждое событие содержит созданный вами референс заказа, поэтому обработчик сводится к switch по типу и поиску на вашей стороне.
Проверяйте подпись, прежде чем доверять телу запроса.
Каждая доставка содержит временную метку и HMAC-подпись исходного тела. Сравнивайте за константное время, отклоняйте всё старше допустимого окна и считайте повторный id события уже обработанным — при ответах не 2xx мы повторяем отправку, поэтому ваш обработчик тоже должен быть идемпотентным.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(rawBody, header, secret) {
const [ts, sig] = header.split(",").map((p) => p.split("=")[1]);
const expected = createHmac("sha256", secret)
.update(`${ts}.${rawBody}`)
.digest("hex");
const a = Buffer.from(sig, "hex");
const b = Buffer.from(expected, "hex");
if (a.length !== b.length || !timingSafeEqual(a, b)) return false;
// Reject replays outside a five-minute window.
return Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}Гарантии
Свойства, на которые можно опереться.
Идемпотентное создание
Каждое создание заказа принимает ключ идемпотентности. Повторный запрос — после таймаута, деплоя или повторной доставки из очереди — вернёт исходный заказ, а не спишет деньги дважды.
Подписанные события с защитой от повтора
Вебхуки несут HMAC-подпись с временной меткой и стабильный id события. Доставка повторяется с backoff, пока ваш endpoint не ответит 2xx, поэтому окно деплоя не приведёт к потере платежа.
Один референс — сквозной
Референс, переданный при создании, встречается в чекауте, чеке, вебхуке, выплате и любом последующем возврате. Второго идентификатора, который нужно сопоставлять между системами, нет.
Тестовый режим — тот же код
Тестовые ключи запускают те же сценарии на тестовых сессиях. Что проходит в тесте, то уходит в продакшн: различаются ключи, которые вы отправляете, а не эндпоинты, которые вызываете.
Тестовые данные
Как проверить важные сценарии.
За каждым сценарием ниже стоит тестовая карта. Они приходят вместе с ключами при выдаче sandbox. Номера у каждого sandbox свои и здесь не публикуются, чтобы оставаться корректными при изменении тестовых диапазонов платёжных систем. Поведение при этом детерминированное: тест так же легко проверяет отказ, как и успешный платёж.
Получите ключи и начните.
Merchant в sandbox с API-ключами, секретами вебхуков и всеми включёнными методами, плюс полная документация: команда сможет интегрироваться до подписания договора.