Розробникам
Три виклики та вебхук.
Gateway — це hosted checkout, тому інтеграція навмисно мінімальна: створити замовлення, відправити клієнта на сторінку, перевірити підписаний результат. Це весь обсяг роботи з вашого боку — платіжний UI, логіку способів оплати, 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 на вашому хості checkout: тому, що видано разом із 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" }
}
}Довідник
Endpoint-и, якими ви справді користуватиметеся.
У документації є більше, але більшість інтеграцій ніколи не виходить за межі цього набору.
Вебхуки
Про що дізнається ваш бекенд.
Кожна подія містить референс замовлення, який ви створили, тож ваш обробник може зводитися до 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, тож вікно деплою не призведе до втрати платежу.
Один референс наскрізно
Референс, який ви передаєте при створенні, з'являється на checkout, у квитанції, вебхуку, виплаті та будь-якому наступному поверненні. Другого ідентифікатора, який треба зіставляти між системами, немає.
Тестовий режим — той самий код
Тестові ключі запускають ті самі сценарії на тестових сесіях. Що проходить у тесті, те й працює в бойовому режимі — різниця лише в ключах, які ви надсилаєте, а не в endpoint-ах, які викликаєте.
Тестові дані
Як перевірити важливі сценарії.
За кожним сценарієм стоїть тестова картка. Їх список ви отримаєте разом із ключами, коли ми видамо sandbox: номери окремі для кожного sandbox і не публікуються тут, тож залишаються чинними, навіть коли схеми змінюють тестові діапазони. Поведінка в будь-якому разі детермінована: тест так само легко перевіряє відмову, як і успішну операцію.
Отримайте ключі й починайте.
Sandbox-мерчант із API-ключами, секретами вебхуків і всіма увімкненими методами — плюс повна документація, щоб ваша команда могла інтегруватися ще до підписання угоди.