Vývojári
Tri volania a webhook.
Gateway je hostovaný checkout, preto je integrácia zámerne malá: vytvoríte objednávku, presmerujete zákazníka na stránku a overíte podpísaný výsledok. Všetko nižšie je celý rozsah — platobné rozhranie, logiku metód, 3-D Secure, peňaženky a potvrdenky vytvárame a udržiavame my.
Prehľad
Voči čomu integrujete.
- REST cez HTTPS
- JSON na vstupe, JSON na výstupe
- API kľúče typu Bearer
- Idempotentné kľúče
- Podpísané webhooky
- Ochrana proti replay útokom
- Testovací a ostrý režim
- SDK pre iOS a Android
- Pluginy pre e-shopy
- Vložené polia
Rýchly štart
Od nuly po zaplatenú objednávku.
Celá úspešná cesta. Sumy sú v najmenších jednotkách meny, referencie určujete vy a na checkout URL presmerujete zákazníka. Základná URL API sa vydáva spolu s kľúčmi do sandboxu — exportujte ju ako PROTOCORE_API_BASE a nižšie uvedené volania pobežia presne tak, ako sú napísané.
Vytvorenie objednávky
Jedno volanie so sumou, menou a vašou vlastnou referenciou. Idempotentný kľúč si generujete sami — opakovaná požiadavka vráti pôvodnú objednávku, nevytvorí druhú.
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"
}'Presmerovanie zákazníka na checkout
Odpoveď obsahuje checkout URL na vašom vlastnom checkout hoste — tom, ktorý dostanete so sandboxom, alebo na vlastnej doméne, keď ju nasmerujete na nás. Presmerujte zákazníka, alebo ju otvorte v SDK; na tej stránke sú platobné metódy, peňaženky aj 3-D Secure, takže na vašej strane nie je čo budovať.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Overenie podpísaného výsledku
Keď platba prejde, na váš endpoint príde podpísaná udalosť. Skôr než jej uveríte, overte podpis voči vášmu webhook secretu a až potom objednávku vybavte podľa referencie, ktorú už poznáte.
{
"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" }
}
}Referencia
Endpointy, ktoré skutočne použijete.
V dokumentácii je toho viac, no toto je sada, z ktorej väčšina integrácií nikdy nevyrastie.
Webhooky
O čom sa dozvie váš backend.
Každá udalosť nesie referenciu objednávky, ktorú ste vytvorili, takže váš handler môže byť len switch podľa typu a vyhľadanie na vašej strane.
Skontrolujte podpis skôr, než uveríte obsahu.
Každé doručenie nesie časovú pečiatku a HMAC podpis surového tela. Porovnávajte v konštantnom čase, odmietnite všetko staršie než vaše tolerančné okno a duplicitné id udalosti berte ako už spracované — pri odpovedi inej než 2xx skúšame znova, takže aj váš handler má byť idempotentný.
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;
}Záruky
Vlastnosti, na ktoré sa môžete spoľahnúť.
Idempotentné vytváranie
Každé vytvorenie objednávky prijíma idempotentný kľúč. Opakovaná požiadavka — po timeoute, nasadení alebo opätovnom doručení z fronty — vráti pôvodnú objednávku a nestrhne platbu dvakrát.
Podpísané udalosti s ochranou proti replay
Webhooky nesú HMAC podpis s časovou pečiatkou a stabilné id udalosti. Doručenie sa opakuje s backoffom, kým váš endpoint neodpovie 2xx, takže okno nasadenia nestojí žiadnu platbu.
Jedna referencia od začiatku do konca
Referencia, ktorú zadáte pri vytvorení, sa objaví na checkoute, v potvrdenke, vo webhooku, vo výplate aj pri každej neskoršej refundácii. Nie je tu druhý identifikátor, ktorý by ste museli mapovať medzi systémami.
Testovací režim je tá istá cesta kódu
Testovacie kľúče spúšťajú identické toky voči testovacím reláciám. Čo prejde v teste, to pôjde do ostrej prevádzky — líši sa to, aké kľúče posielate, nie ktoré endpointy voláte.
Testovacie dáta
Ako vyskúšať cesty, na ktorých záleží.
Za každou cestou nižšie stojí testovacia karta, ktorú nájdete spolu s kľúčmi pri vydaní sandboxu. Čísla sú pre každý sandbox vlastné a nezverejňujeme ich tu, aby zostali správne aj pri zmene testovacích rozsahov kartových schém. Správanie je v oboch prípadoch deterministické: test si overí zamietnutie rovnako ľahko ako úspech.
Získajte kľúče a začnite.
Sandbox obchodník s API kľúčmi, webhook secretmi a zapnutými všetkými metódami — plus kompletná referencia, aby váš tím mohol integrovať ešte pred podpisom zmluvy.