Fejlesztőknek
Három hívás és egy webhook.
A Gateway egy hosted checkout, ezért az integráció szándékosan kicsi: hozz létre egy rendelést, irányítsd az ügyfelet az oldalra, ellenőrizd az aláírt eredményt. Az alábbiakban a teljes felület szerepel — a fizetési felületet, a módszerek logikáját, a 3-D Secure-t, a walleteket és a nyugtákat mi építjük és tartjuk naprakészen.
Dióhéjban
Mivel integrálsz.
- REST HTTPS felett
- JSON be, JSON ki
- Bearer API-kulcsok
- Idempotencia-kulcsok
- Aláírt webhookok
- Replay-védelem
- Teszt és éles mód
- iOS és Android SDK-k
- Webshop-pluginek
- Beágyazott mezők
Gyorsindítás
A semmitől a kifizetett rendelésig.
A teljes sikeres folyamat. Az összegek a legkisebb pénzegységben értendők, a hivatkozások a tieid, a checkout URL pedig az, ahová az ügyfelet átirányítod. Az API alap-URL-t a sandbox-kulcsokkal együtt kapod — exportáld PROTOCORE_API_BASE néven, és az alábbi hívások pontosan így működnek.
Rendelés létrehozása
Egyetlen hívás az összeggel, a pénznemmel és a saját hivatkozásoddal. Az idempotencia-kulcsot te generálod — az újraküldött kérés az eredeti rendelést adja vissza, nem hoz létre másodikat.
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"
}'Az ügyfél átirányítása a checkoutra
A válasz tartalmaz egy checkout URL-t a saját checkout hosztodon — azon, amelyet a sandboxszal kaptál, vagy a saját domaineden, ha ráirányítod hozzánk. Irányítsd oda az ügyfelet, vagy nyisd meg az SDK-ban; a módszerek, a walletek és a 3-D Secure ezen az oldalon élnek, így neked nincs mit építened.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Az aláírt eredmény ellenőrzése
A fizetés befejeztével egy aláírt esemény érkezik a végpontodra. Mielőtt bármiben megbíznál, ellenőrizd az aláírást a webhook secreted alapján, majd teljesíts a már ismert hivatkozás szerint.
{
"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
Azok a végpontok, amelyeket tényleg használni fogsz.
A dokumentációban több is van, de a legtöbb integráció ennél a készletnél tovább sosem jut.
Webhookok
Miről értesül a backendod.
Minden esemény tartalmazza az általad létrehozott rendelés hivatkozását, így a kezelőd egy típus szerinti switch és egy saját oldali keresés is lehet.
Az aláírást ellenőrizd, mielőtt a törzsben megbízol.
Minden kézbesítés időbélyeget és a nyers törzsre számolt HMAC-aláírást tartalmaz. Az összehasonlítás konstans idejű legyen, utasíts el mindent, ami régebbi a tűrési ablakodnál, a duplikált eseményazonosítót pedig kezeld már feldolgozottként — nem 2xx válasz esetén újrapróbálkozunk, ezért a kezelődnek is idempotensnek kell lennie.
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;
}Garanciák
Tulajdonságok, amelyekre építhetsz.
Idempotens létrehozás
Minden rendeléslétrehozás idempotencia-kulcsot fogad. Az újraküldött kérés — időtúllépés, deploy vagy üzenetsor-újrakézbesítés után — az eredeti rendelést adja vissza, nem terhel kétszer.
Aláírt, replay-védett események
A webhookok időbélyeges HMAC-aláírást és stabil eseményazonosítót kapnak. A kézbesítés backoffal újrapróbálkozik, amíg a végpontod 2xx-szel nem válaszol, így egy deploy-ablak nem veszít el fizetést.
Egy hivatkozás, végig
A létrehozáskor megadott hivatkozás megjelenik a checkouton, a nyugtán, a webhookban, a kifizetésen és minden későbbi visszatérítésen. Nincs második azonosító, amelyet rendszerek között kellene megfeleltetni.
A teszt mód ugyanaz a kódút
A teszt kulcsok ugyanazokat a folyamatokat futtatják teszt munkameneteken. Ami tesztben átmegy, az megy élesbe — a különbség a küldött kulcsban van, nem a hívott végpontokban.
Tesztadatok
Hogyan próbáld ki a fontos útvonalakat.
Minden alábbi útvonalhoz tartozik egy tesztkártya, amelyet a sandbox kiadásakor a kulcsokkal együtt kapsz meg. A számokat sandboxonként adjuk meg, és nem tesszük közzé itt, így azok a kártyatársaságok tesztsávjainak változásakor is helyesek maradnak. A működés mindkét esetben determinisztikus: egy teszt ugyanolyan könnyen ellenőrizhet elutasítást, mint sikeres tranzakciót.
Kérj kulcsokat, és kezdj bele.
Egy sandbox kereskedői fiók API-kulcsokkal, webhook-titkokkal és minden bekapcsolt fizetési móddal — plusz a teljes referencia, hogy a csapatod már az aláírás előtt integrálhasson.