Programeri
Tri poziva i jedan webhook.
Gateway je hostovani checkout, pa je integracija namerno mala: kreirate porudžbinu, pošaljete kupca na stranicu i proverite potpisani rezultat. Ovo dole je cela površina — platni UI, logika metoda plaćanja, 3-D Secure, digitalni novčanici i potvrde su naš posao da ih gradimo i održavamo ažurnim.
Ukratko
Na šta se integrišete.
- 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 režim
- iOS & Android SDK-ovi
- Plugini za prodavnice
- Ugrađena polja
Brzi start
Od nule do plaćene porudžbine.
Ceo srećni put. Iznosi su u najmanjim jedinicama valute, reference su vaše, a checkout URL je adresa na koju preusmeravate 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 porudžbinu
Jedan poziv sa iznosom, valutom i vašom referencom. Ključ idempotentnosti generišete sami — ponovljen zahtev vraća prvobitnu porudžbinu umesto da napravi 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 dobijate uz sandbox, ili na vašem domenu kada ga usmerite na nas. Preusmerite kupca na njega ili ga otvorite u SDK-u; na toj stranici žive metode plaćanja, novčanici i 3-D Secure, tako da s vaše strane nema šta da se gradi.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Proverite potpisani rezultat
Kada se plaćanje završi, potpisani događaj stiže na vaš endpoint. Proverite potpis pomoću webhook tajne pre nego što bilo čemu poverujete, 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 kog većina integracija nikad ne izlazi.
Webhookovi
Šta vaš backend čuje.
Svaki događaj nosi referencu porudžbine koju ste kreirali, pa vaš handler može biti običan switch po tipu i pretraga na vašoj strani.
Proverite potpis pre nego što poverujete sadržaju.
Svaka isporuka nosi timestamp i HMAC potpis nad sirovim telom zahteva. Poredite u konstantnom vremenu, odbacite sve starije od vašeg dozvoljenog prozora i duplikat id-a događaja tretirajte kao već obrađen — slanje ponavljamo kad odgovor nije 2xx, pa i vaš handler treba da bude 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
Osobine na koje se možete osloniti.
Idempotentno kreiranje
Svako kreiranje porudžbine prima ključ idempotentnosti. Ponovljen zahtev — posle timeouta, deploya ili ponovne isporuke iz reda — vraća prvobitnu porudžbinu umesto da naplati dvaput.
Potpisani događaji sa zaštitom od replay napada
Webhookovi nose HMAC potpis sa vremenskom oznakom i stabilan id događaja. Isporuka se ponavlja uz backoff dok vaš endpoint ne odgovori sa 2xx, pa prozor deploya ne gubi plaćanje.
Jedna referenca, od početka do kraja
Referenca koju date pri kreiranju pojavljuje se na checkoutu, potvrdi, webhooku, isplati i svakoj kasnijoj refundaciji. Nema drugog identifikatora koji treba mapirati između sistema.
Test režim koristi 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 ključevima koje šaljete, a ne u endpointima koje pozivate.
Test podaci
Kako isprobati putanje koje su bitne.
Iza svake putanje u nastavku stoji test kartica, navedena uz vaše ključeve kada se izda sandbox — brojevi su po sandboxu, a ne objavljeni ovde, pa ostaju tačni kad se promene test opsezi šema. Ponašanje je u oba slučaja determinističko: test jednako lako proverava odbijanje kao i uspeh.
Uzmite ključeve i počnite.
Sandbox trgovac sa API ključevima, webhook tajnama i uključenim svim metodama — plus kompletna referenca, da vaš tim može da integriše pre nego što se bilo šta potpiše.