Za developere
Tri poziva i jedan webhook.
Gateway je hostani checkout, pa je integracija namjerno mala: kreirate narudžbu, kupca šaljete na stranicu, provjeravate potpisani rezultat. Ovo je cijela površina — sučelje za plaćanje, logiku metoda, 3-D Secure, novčanike i potvrde gradimo i održavamo mi.
Ukratko
Na što se integrirate.
- REST preko HTTPS-a
- JSON na ulazu, JSON na izlazu
- Bearer API ključevi
- Ključevi idempotentnosti
- Potpisani webhookovi
- Zaštita od replay napada
- Test i live način rada
- iOS i Android SDK-ovi
- Pluginovi za webshopove
- Ugrađena polja
Brzi početak
Od ničega do plaćene narudžbe.
Cijeli happy path. Iznosi su u najmanjim jedinicama valute, reference su vaše, a checkout URL je adresa na koju preusmjeravate kupca. Osnovni API URL dobivate uz sandbox ključeve — izvezite ga kao PROTOCORE_API_BASE i pozivi u nastavku rade točno kako su napisani.
Kreirajte narudžbu
Jedan poziv s iznosom, valutom i vlastitom referencom. Idempotency ključ generirate sami — ponovljeni zahtjev vraća izvornu narudžbu umjesto da kreira drugu.
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"
}'Pošaljite kupca na checkout
Odgovor sadrži checkout URL na vašem checkout hostu — onom izdanom uz sandbox ili na vlastitoj domeni kad je usmjerite na nas. Preusmjerite kupca na njega ili ga otvorite u SDK-u; na toj stranici žive metode plaćanja, novčanici i 3-D Secure, pa s vaše strane nema što graditi.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Provjerite potpisani rezultat
Kad se plaćanje završi, potpisani događaj stiže na vaš endpoint. Prije nego što bilo čemu povjerujete, provjerite potpis pomoću webhook secreta, a zatim izvršite narudžbu prema referenci koju već poznajete.
{
"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" }
}
}Referenca
Endpointi koje ćete stvarno koristiti.
U dokumentaciji ima i više, ali ovo je skup preko kojeg većina integracija nikad ne preraste.
Webhookovi
O čemu vaš backend saznaje.
Svaki događaj nosi referencu narudžbe koju ste kreirali, pa vaš handler može biti switch po tipu i pretraživanje na vašoj strani.
Provjerite potpis prije nego povjerujete sadržaju.
Svaka isporuka nosi vremensku oznaku i HMAC potpis nad sirovim tijelom zahtjeva. Usporedite u konstantnom vremenu, odbacite sve starije od vašeg dopuštenog prozora i duplicirani id događaja smatrajte već obrađenim — slanje ponavljamo nakon odgovora koji nije 2xx, pa i vaš handler treba biti idempotentan.
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;
}Jamstva
Svojstva na koja se možete osloniti.
Idempotentno kreiranje
Svako kreiranje narudžbe prima idempotency ključ. Ponovljeni zahtjev — nakon timeouta, deploya ili ponovne isporuke iz reda — vraća izvornu narudžbu umjesto da naplati dvaput.
Potpisani događaji sa zaštitom od replaya
Webhookovi nose HMAC potpis s vremenskom oznakom i stabilan id događaja. Isporuke se ponavljaju s backoffom dok vaš endpoint ne odgovori s 2xx, pa prozor deploya ne gubi plaćanje.
Jedna referenca, od početka do kraja
Referenca koju pošaljete pri kreiranju pojavljuje se na checkoutu, potvrdi, webhooku, isplati i svakom kasnijem povratu. Nema drugog identifikatora koji biste morali mapirati među sustavima.
Test način rada je isti kod
Test ključevi pokreću identične tokove nad testnim sesijama. Što prođe u testu, ide u produkciju — razlika je u ključevima koje šaljete, a ne u endpointima koje pozivate.
Testni podaci
Kako provjeriti putanje koje su važne.
Iza svakog scenarija ispod stoji testna kartica, navedena uz vaše ključeve kad se izda sandbox — brojevi su po sandboxu, a ne objavljeni ovdje, pa ostaju ispravni i kad se promijene testni rasponi card schemea. Ponašanje je u svakom slučaju determinističko: test se jednako lako oslanja na odbijanje kao i na uspjeh.
Uzmite ključeve i krenite.
Sandbox trgovac s API ključevima, webhook tajnama i uključenim svim metodama — plus cjelovita dokumentacija, da vaš tim može integrirati prije nego što se išta potpiše.