Developeri
Tri poziva i jedan webhook.
Gateway je hostirani checkout, pa je integracija namjerno mala: kreirajte narudžbu, pošaljite kupca na stranicu, provjerite potpisani rezultat. Ovo je cijela površina — platni UI, logiku metoda, 3-D Secure, novčanike i potvrde mi gradimo i održavamo ažurnim.
Ukratko
Na šta se integrirate.
- REST preko HTTPS-a
- JSON na ulazu, JSON na izlazu
- Bearer API ključevi
- Ključevi idempotentnosti
- Potpisani webhookovi
- Zaštita od ponovnog slanja
- Test i live način rada
- iOS & Android SDK-ovi
- Plugini za webshopove
- Ugrađena polja
Brzi start
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 URL API-ja dobijate uz sandbox ključeve — izvezite ga kao PROTOCORE_API_BASE i pozivi ispod rade tačno kako su napisani.
Kreirajte narudžbu
Jedan poziv s iznosom, valutom i vašom referencom. Idempotency ključ generirate vi — ponovljeni zahtjev vraća originalnu 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 koji dobijete uz sandbox, ili na vašoj domeni kad je usmjerite na nas. Preusmjerite kupca na njega ili ga otvorite u SDK-u; na toj stranici su metode plaćanja, novčanici i 3-D Secure, tako da s vaše strane nema ništa za izgraditi.
{
"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, pa isporučite prema referenci koju već znate.
{
"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 zaista koristiti.
U dokumentaciji ima i više, ali ovo je skup preko kojeg većina integracija nikad ne izraste.
Webhookovi
O čemu vaš backend čuje.
Svaki događaj nosi referencu narudžbe koju ste kreirali, pa vaš handler može biti switch po tipu i pretraga na vašoj strani.
Provjerite potpis prije nego što povjerujete tijelu zahtjeva.
Svaka isporuka nosi vremensku oznaku i HMAC potpis nad sirovim tijelom. Poredite u konstantnom vremenu, odbijte sve starije od vašeg dozvoljenog prozora i duplikat id-a događaja tretirajte kao već obrađen — ponavljamo slanje na odgovore koji nisu 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;
}Garancije
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 originalnu narudžbu umjesto da naplati dvaput.
Potpisani događaji sa zaštitom od ponovnog slanja
Webhookovi nose HMAC potpis s vremenskom oznakom i stabilan id događaja. Isporuke se ponavljaju s backoffom dok vaš endpoint ne odgovori sa 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 treba mapirati između sistema.
Test način rada je isti kod
Test ključevi pokreću identične tokove nad test sesijama. Što prođe u testu, to ide u produkciju — razlika je u tome koje ključeve šaljete, a ne koje endpointe pozivate.
Testni podaci
Kako provjeriti putanje koje su bitne.
Iza svake putanje u nastavku stoji testna kartica. Brojevi se navode uz vaše ključeve kada se izda sandbox — oni su po sandboxu, a ne objavljeni ovdje, pa ostaju ispravni kada se testni rasponi šema promijene. Ponašanje je u oba slučaja determinističko: test može provjeriti odbijanje jednako lako kao i uspjeh.
Uzmite ključeve i počnite.
Sandbox trgovac s API ključevima, webhook tajnama i uključenim svim metodama — plus kompletna referenca, da vaš tim može integrirati prije nego što se išta potpiše.