За разработчици
Три заявки и един webhook.
Gateway е хостван checkout, затова интеграцията е нарочно малка: създавате поръчка, пренасочвате клиента към страницата и проверявате подписания резултат. Всичко по-долу е цялата повърхност — платежният интерфейс, логиката на методите, 3-D Secure, портфейлите и разписките са наша грижа и ние ги поддържаме актуални.
Накратко
С какво се интегрирате.
- REST през HTTPS
- JSON на входа, JSON на изхода
- Bearer API ключове
- Idempotency ключове
- Подписани webhooks
- Защита срещу replay
- Тестов и реален режим
- SDK за iOS и Android
- Плъгини за магазини
- Вградени полета
Бърз старт
От нищо до платена поръчка.
Целият щастлив път. Сумите са в минимални единици, референциите са ваши, а checkout URL е адресът, към който пренасочвате клиента. Базовият URL на API се издава заедно с вашите sandbox ключове — експортирайте го като PROTOCORE_API_BASE и заявките по-долу работят точно както са написани.
Създаване на поръчка
Една заявка със сумата, валутата и вашата собствена референция. Idempotency ключът се генерира от вас — повторената заявка връща първоначалната поръчка, вместо да създаде втора.
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 стига подписано събитие. Преди да се доверите на каквото и да е, проверете подписа със своя webhook secret, след което изпълнете поръчката по референцията, която вече знаете.
{
"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-ите, които наистина ще ползвате.
В документацията има още, но повечето интеграции не надхвърлят този набор.
Webhooks
За какво чува вашият бекенд.
Всяко събитие носи референцията на поръчката, която сте създали, така че обработчикът ви може да е switch по типа и търсене при вас.
Проверявайте подписа, преди да се доверите на съдържанието.
Всяко доставяне носи timestamp и 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;
}Гаранции
Свойствата, върху които можете да градите.
Идемпотентно създаване
Всяко създаване на поръчка приема idempotency ключ. Повторена заявка — след timeout, деплой или повторна доставка от опашка — връща първоначалната поръчка, вместо да таксува два пъти.
Подписани събития със защита срещу replay
Webhooks носят HMAC подпис с timestamp и стабилен id на събитие. Доставките се повтарят с backoff, докато endpoint-ът ви не отговори с 2xx, така че деплойът не губи плащане.
Една референция от край до край
Референцията, която подавате при създаване, се появява в checkout, разписката, webhook-а, изплащането и всяко по-късно възстановяване. Няма втори идентификатор, който да съпоставяте между системите.
Тестовият режим е същият код
Тестовите ключове изпълняват същите потоци срещу тестови сесии. Което минава в тест, това излиза в продукция — разликата е в ключовете, които изпращате, а не в endpoint-ите, които викате.
Тестови данни
Как да изпробвате важните пътища.
Зад всеки сценарий по-долу стои тестова карта. Ще я намерите заедно с ключовете, когато получите sandbox средата — номерата са за конкретния sandbox и не се публикуват тук, така че остават верни, когато схемите променят тестовите си диапазони. И в двата случая поведението е детерминирано: тестът може да потвърди отказ също толкова лесно, колкото и успешно плащане.
Вземете ключове и започнете.
Sandbox търговец с API ключове, webhook тайни и включени всички методи — плюс пълната документация, за да може екипът ви да интегрира, преди да е подписано каквото и да било.