Програмери
Три повици и еден webhook.
Gateway е checkout што го хостираме ние, па интеграцијата е намерно мала: креирате нарачка, го праќате клиентот на страницата, го верификувате потпишаниот резултат. Тоа е целата површина — платежниот интерфејс, логиката на методите, 3-D Secure, паричниците и признаниците ги градиме и ги одржуваме ажурни ние.
Општа слика
Со што се интегрирате.
- REST преку HTTPS
- JSON на влез, JSON на излез
- Bearer API клучеви
- Idempotency клучеви
- Потпишани webhooks
- Заштита од replay
- Тест и live режим
- iOS и Android SDK
- Плагини за продавници
- Вградени полиња
Брз почеток
Од ништо до платена нарачка.
Целата среќна патека. Износите се во најмали единици, референците ги задавате вие, а checkout URL-то е адресата на која го пренасочувате клиентот. API base URL-то се издава со вашите 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 host — оној издаден со 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 тајна, па потоа исполнете ја нарачката според референцата што веќе ја знаете.
{
"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
Што слуша вашиот backend.
Секој настан ја носи референцата на нарачката што сте ја креирале, па вашиот handler може да биде switch по типот и пребарување кај вас.
Проверете го потписот пред да му верувате на телото.
Секоја испорака носи timestamp и HMAC потпис врз суровото тело. Споредувајте во константно време, одбијте сè постаро од вашиот прозорец на толеранција, а дупликат event id сметајте го за веќе обработен — повторуваме при одговори различни од 2xx, па и вашиот handler треба да биде idempotent.
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;
}Гаранции
Својствата врз кои можете да градите.
Idempotent креирања
Секое креирање нарачка прима idempotency клуч. Повторено барање — по timeout, deploy или повторна испорака од редица — ја враќа оригиналната нарачка наместо да наплати двапати.
Потпишани настани со заштита од replay
Webhooks носат HMAC потпис со timestamp и стабилен event id. Испораките се повторуваат со backoff сè додека вашиот endpoint не одговори со 2xx, па прозорецот на deploy не губи плаќање.
Една референца, од крај до крај
Референцата што ја задавате при креирањето се појавува на checkout-от, признаницата, webhook-от, исплатата и секое подоцнежно рефундирање. Нема втор идентификатор што треба да го мапирате меѓу системите.
Тест режимот е истата патека на код
Тест клучевите ги извршуваат истите текови врз тест сесии. Она што поминува во тест, тоа оди во продукција — разликата е кои клучеви ги праќате, а не кои endpoint-и ги повикувате.
Тест податоци
Како да ги проверите патеките што се важни.
Зад секоја патека стои тест-картичка, наведена заедно со вашите клучеви при издавањето на sandbox-от. Бројките се по sandbox и не се објавени овде, па остануваат точни кога шемите ги менуваат тест-опсезите. Однесувањето е детерминистичко во секој случај: тестот проверува одбивање исто толку лесно како и успех.
Земете клучеви и започнете.
Sandbox трговец со API клучеви, webhook тајни и вклучени сите методи — плус целосната референца, за вашиот тим да интегрира пред да се потпише каков било договор.