Forritarar
Þrjú köll og eitt webhook.
Gateway er hýst checkout, svo samþættingin er viljandi lítil: stofnaðu pöntun, sendu viðskiptavininn á síðuna og staðfestu undirritaða niðurstöðu. Allt hér fyrir neðan er allt sem þarf — greiðsluviðmótið, rökvísi greiðsluleiða, 3-D Secure, veski og kvittanir eru á okkar könnu, bæði smíði og viðhald.
Í stuttu máli
Það sem þú tengist við.
- REST yfir HTTPS
- JSON inn, JSON út
- Bearer API-lyklar
- Idempotency-lyklar
- Undirrituð webhooks
- Vörn gegn endurspilun
- Prófunarhamur og raunhamur
- iOS- og Android-SDK
- Viðbætur fyrir vefverslanir
- Innbyggðir reitir
Flýtibyrjun
Frá engu í greidda pöntun.
Öll leiðin þegar allt gengur upp. Upphæðir eru í smæstu einingum, tilvísanir eru þínar og checkout-slóðin er sú sem þú vísar viðskiptavininum á. Slóð API fylgir sandkassalyklunum þínum — flyttu hana út sem PROTOCORE_API_BASE og köllin hér að neðan keyra nákvæmlega eins og þau standa.
Stofna pöntun
Eitt kall með upphæð, gjaldmiðli og þinni eigin tilvísun. Idempotency-lykillinn kemur frá þér — endurtekin beiðni skilar upphaflegu pöntuninni í stað þess að stofna aðra.
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"
}'Sendu viðskiptavininn í checkout
Svarið inniheldur checkout-slóð á þitt eigið checkout-lén — það sem fylgir sandkassanum eða þitt eigið lén þegar þú beinir því til okkar. Vísaðu áfram á hana eða opnaðu hana í SDK; á þeirri síðu eru greiðsluleiðirnar, veskin og 3-D Secure, svo þú þarft ekkert að smíða.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Staðfestu undirritaða niðurstöðu
Þegar greiðslu lýkur berst undirritaður atburður á endapunktinn þinn. Staðfestu undirskriftina með webhook-leyndarmálinu áður en þú treystir nokkru og afgreiddu síðan út frá tilvísuninni sem þú þekkir þegar.
{
"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" }
}
}Tilvísun
Endapunktarnir sem þú munt í raun nota.
Meira er að finna í skjölunum, en þetta er það sem flestar samþættingar vaxa aldrei upp úr.
Webhooks
Það sem bakendinn þinn fær að vita.
Hver atburður ber tilvísun pöntunarinnar sem þú stofnaðir, svo meðhöndlarinn þinn getur verið einfalt switch á tegund og uppflettiing í þínu eigin kerfi.
Athugaðu undirskriftina áður en þú treystir innihaldinu.
Hver sending ber tímastimpil og HMAC-undirskrift yfir óunninn texta beiðninnar. Berðu saman í föstum tíma, hafnaðu öllu sem er eldra en leyfilegt tímabil og líttu á tvítekið atburðarauðkenni sem þegar meðhöndlað — við reynum aftur ef svarið er ekki 2xx, svo meðhöndlarinn þinn ætti einnig að vera idempotent.
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;
}Ábyrgðir
Eiginleikarnir sem þú getur byggt á.
Idempotent stofnun
Sérhver pöntunarstofnun tekur við idempotency-lykli. Endurtekin beiðni — eftir tímamörk, uppfærslu eða endursendingu úr biðröð — skilar upphaflegu pöntuninni í stað þess að skuldfæra tvisvar.
Undirritaðir atburðir með vörn gegn endurspilun
Webhooks bera tímastimplaða HMAC-undirskrift og stöðugt atburðarauðkenni. Sendingar eru reyndar aftur með vaxandi bili þar til endapunkturinn svarar 2xx, svo uppfærsluglugginn glatar ekki greiðslu.
Ein tilvísun, frá upphafi til enda
Tilvísunin sem þú gefur við stofnun birtist á checkout, kvittun, webhook, útgreiðslu og hverri síðari endurgreiðslu. Ekkert annað auðkenni þarf að varpa á milli kerfa.
Prófunarhamur er sama kóðaleið
Prófunarlyklar keyra sömu ferla gegn prófunarlotum. Það sem stenst í prófun er það sem fer í loftið — munurinn er hvaða lyklar eru sendir, ekki hvaða endapunkta þú kallar á.
Prófunargögn
Hvernig á að æfa mikilvægu leiðirnar.
Á bak við hverja leið hér að neðan er prófunarkort, sem fylgir lyklunum þegar sandkassinn er afhentur. Númerin eru sértæk fyrir hvern sandkassa en ekki birt hér, svo þau haldist rétt þegar prófunarsvið korthafakerfanna breytast. Hegðunin er í báðum tilvikum fyrirsjáanleg: prófun getur staðfest synjun jafn auðveldlega og árangursríka heimild.
Fáðu lykla og byrjaðu.
Sandkassaseljandi með API-lyklum, webhook-leyndarmálum og öllum greiðsluleiðum virkum — ásamt fullri tækniskjölun, svo teymið þitt geti hafið samþættingu áður en nokkuð er undirritað.