Kūrėjams
Trys užklausos ir webhook.
Gateway yra talpinamas checkout, todėl integracija sąmoningai maža: sukurkite užsakymą, nukreipkite pirkėją į puslapį, patikrinkite pasirašytą rezultatą. Žemiau — visa jūsų pusės sąsaja: mokėjimo sąsają, būdų logiką, 3-D Secure, pinigines ir kvitus kuriame bei atnaujiname mes.
Bendras vaizdas
Su kuo integruojatės.
- REST per HTTPS
- JSON įėjime, JSON išėjime
- Bearer API raktai
- Idempotentiškumo raktai
- Pasirašyti webhook'ai
- Apsauga nuo pakartotinio siuntimo
- Testinis ir realus režimai
- iOS ir Android SDK
- Parduotuvių įskiepiai
- Įterpiami laukai
Greita pradžia
Nuo nulio iki apmokėto užsakymo.
Visas sėkmingas scenarijus. Sumos nurodomos mažiausiais vienetais, reference nustatote jūs, o checkout URL — adresas, į kurį nukreipiate pirkėją. API bazinis URL išduodamas kartu su sandbox raktais — eksportuokite jį kaip PROTOCORE_API_BASE ir žemiau pateiktos užklausos veiks tiksliai taip, kaip parašyta.
Sukurkite užsakymą
Viena užklausa su suma, valiuta ir jūsų pačių reference. Idempotentiškumo raktą generuojate jūs — pakartota užklausa grąžina pirminį užsakymą, o ne sukuria antrą.
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"
}'Nukreipkite pirkėją į checkout
Atsakyme pateikiamas checkout URL jūsų checkout domene — išduotame su sandbox arba jūsų pačių, kai nukreipsite jį pas mus. Nukreipkite pirkėją arba atidarykite jį per SDK; šiame puslapyje veikia mokėjimo būdai, piniginės ir 3-D Secure, tad jūsų pusėje nieko kurti nereikia.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Patikrinkite pasirašytą rezultatą
Kai mokėjimas baigiamas, į jūsų endpoint atkeliauja pasirašytas įvykis. Prieš kuo nors pasitikėdami, patikrinkite parašą pagal savo webhook paslaptį, tada vykdykite užsakymą pagal jau žinomą reference.
{
"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" }
}
}Žinynas
Endpoint'ai, kuriuos iš tikrųjų naudosite.
Dokumentacijoje rasite daugiau, bet daugelis integracijų neišauga už šio rinkinio ribų.
Webhooks
Apie ką sužino jūsų backend.
Kiekvienas įvykis turi jūsų sukurto užsakymo reference, todėl jūsų tvarkyklė gali būti tiesiog switch pagal tipą ir paieška jūsų pusėje.
Patikrinkite parašą, prieš pasitikėdami turiniu.
Kiekvienas siuntimas turi laiko žymą ir HMAC parašą nuo neapdoroto turinio. Lyginkite pastoviu laiku, atmeskite viską, kas senesnė už jūsų leistiną langą, o pasikartojantį įvykio id laikykite jau apdorotu — kartojame, kai gauname ne 2xx atsakymą, todėl jūsų tvarkyklė taip pat turi būti idempotentiška.
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;
}Garantijos
Savybės, kuriomis galite pasikliauti.
Idempotentiški sukūrimai
Kiekvienas užsakymo sukūrimas priima idempotentiškumo raktą. Pakartota užklausa — po timeout, diegimo ar eilės pakartotinio pristatymo — grąžina pirminį užsakymą, o ne nuskaito pinigus dukart.
Pasirašyti įvykiai su apsauga nuo pakartojimo
Webhooks turi laiko žymos HMAC parašą ir pastovų įvykio id. Siuntimas kartojamas su didėjančiais tarpais, kol jūsų endpoint atsako 2xx, todėl diegimo langas nepraranda mokėjimo.
Viena reference nuo pradžios iki galo
Kuriant nurodyta reference matoma checkout, kvite, webhook, išmokoje ir vėlesniame grąžinime. Nėra antro identifikatoriaus, kurį tektų susieti tarp sistemų.
Testinis režimas — tas pats kodo kelias
Testiniai raktai vykdo tuos pačius srautus testinėse sesijose. Kas veikia teste, tas veiks ir realiai — skiriasi tik siunčiami raktai, o ne kviečiami endpoint'ai.
Testiniai duomenys
Kaip išbandyti svarbiausius scenarijus.
Kiekvieną žemiau pateiktą scenarijų atitinka testinė kortelė — jos pateikiamos kartu su raktais, kai išduodama sandbox aplinka. Numeriai skiriasi kiekvienoje aplinkoje ir čia neskelbiami, kad išliktų teisingi keičiantis schemų testiniams diapazonams. Elgsena visais atvejais deterministinė: testas gali patikrinti atmetimą taip pat lengvai, kaip ir sėkmingą operaciją.
Gaukite raktus ir pradėkite.
Sandbox prekybininkas su API raktais, webhook paslaptimis ir įjungtais visais metodais — taip pat pilna dokumentacija, kad jūsų komanda galėtų integruoti dar prieš pasirašant sutartį.