Razvijalci
Trije klici in webhook.
Gateway je gostovani checkout, zato je integracija namenoma majhna: ustvarite naročilo, stranko pošljete na stran, preverite podpisan rezultat. Spodaj je celotna površina — plačilni vmesnik, logika načinov plačila, 3-D Secure, denarnice in potrdila so naša skrb: mi jih gradimo in posodabljamo.
Zgradba
S čim se povezujete.
- REST prek HTTPS
- JSON noter, JSON ven
- API ključi Bearer
- Ključi idempotentnosti
- Podpisani webhooki
- Zaščita pred ponovitvijo (replay)
- Testni in produkcijski način
- SDK-ja za iOS in Android
- Vtičniki za trgovine
- Vgrajena polja
Hitri začetek
Od nič do plačanega naročila.
Celotna srečna pot. Zneski so v najmanjših enotah, reference so vaše, URL checkouta pa je naslov, kamor preusmerite stranko. Osnovni URL API-ja dobite skupaj s ključi za sandbox — izvozite ga kot PROTOCORE_API_BASE in spodnji klici delujejo natanko tako, kot so zapisani.
Ustvarite naročilo
En klic z zneskom, valuto in vašo lastno referenco. Ključ idempotentnosti generirate sami — ponovljena zahteva vrne prvotno naročilo, namesto da bi ustvarila drugo.
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"
}'Stranko pošljite na checkout
Odgovor vsebuje URL checkouta na vašem checkout gostitelju — tistem, ki ste ga dobili s sandboxom, ali na vaši domeni, ko jo usmerite k nam. Preusmerite stranko nanj ali ga odprite v SDK-ju; na tej strani so načini plačila, denarnice in 3-D Secure, zato na vaši strani ni ničesar za graditi.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Preverite podpisan rezultat
Ko je plačilo zaključeno, na vašo končno točko prispe podpisan dogodek. Preden karkoli vzamete za resnično, preverite podpis z vašo skrivnostjo webhooka, nato izpolnite naročilo glede na referenco, ki jo že poznate.
{
"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
Končne točke, ki jih boste res uporabljali.
V dokumentaciji je več, a to je nabor, čez katerega večina integracij nikoli ne zraste.
Webhooki
O čem se sliši vaše zaledje.
Vsak dogodek nosi referenco naročila, ki ste jo ustvarili, zato je vaš handler lahko le switch po tipu in iskanje na vaši strani.
Preverite podpis, preden zaupate telesu zahteve.
Vsaka dostava vsebuje časovni žig in podpis HMAC nad surovim telesom. Primerjajte v konstantnem času, zavrnite vse, kar je starejše od vašega okna tolerance, in podvojen id dogodka obravnavajte kot že obdelan — ob odgovorih, ki niso 2xx, poskusimo znova, zato naj bo idempotenten tudi vaš handler.
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
Lastnosti, na katere se lahko zanesete pri gradnji.
Idempotentno ustvarjanje
Vsako ustvarjanje naročila sprejme ključ idempotentnosti. Ponovljena zahteva — po časovni omejitvi, deployu ali ponovni dostavi iz vrste — vrne prvotno naročilo, namesto da bi bremenila dvakrat.
Podpisani dogodki z zaščito pred ponovitvijo
Webhooki nosijo podpis HMAC s časovnim žigom in stabilen id dogodka. Dostave se ponavljajo z umikom (backoff), dokler vaša končna točka ne odgovori z 2xx, zato okno deploya ne izgubi plačila.
Ena referenca, od začetka do konca
Referenca, ki jo podate ob ustvarjanju, se pojavi na checkoutu, potrdilu, webhooku, izplačilu in vseh poznejših vračilih. Drugega identifikatorja, ki bi ga morali preslikovati med sistemi, ni.
Testni način je ista koda
Testni ključi poganjajo enake tokove na testnih sejah. Kar gre skozi v testu, gre v produkcijo — razlika je v tem, katere ključe pošljete, ne katere končne točke kličete.
Testni podatki
Kako preizkusiti poti, ki štejejo.
Za vsako pot spodaj obstaja testna kartica, navedena skupaj z vašimi ključi ob izdaji sandboxa. Številke so za vsak sandbox posebej in tu niso objavljene, zato ostanejo pravilne, ko se testni razponi shem spremenijo. Obnašanje je v vsakem primeru determinističnog: test enako zlahka preveri zavrnitev kot uspeh.
Pridobite ključe in začnite.
Sandbox trgovec s ključi API, skrivnostmi webhookov in vklopljenimi vsemi metodami — plus celotna referenca, da lahko vaša ekipa integrira, še preden je karkoli podpisano.