Zhvillues
Tre thirrje dhe një webhook.
Gateway është një checkout i hostuar, prandaj integrimi është qëllimisht i vogël: krijoni një porosi, dërgoni klientin te faqja, verifikoni rezultatin e nënshkruar. Gjithçka më poshtë është e gjithë sipërfaqja — ndërfaqen e pagesës, logjikën e metodave, 3-D Secure, portofolet dhe faturat i ndërtojmë dhe i mbajmë të përditësuara ne.
Në përmbledhje
Çfarë po integroni.
- REST mbi HTTPS
- JSON hyrje, JSON dalje
- Çelësa API Bearer
- Çelësa idempotence
- Webhooks të nënshkruar
- Mbrojtje nga riprodhimi
- Modalitete test dhe live
- SDK për iOS & Android
- Plugin-e për dyqane
- Fusha të integruara
Fillim i shpejtë
Nga zero te një porosi e paguar.
Rruga e plotë e suksesshme. Shumat janë në njësi minore, referencat janë tuajat, dhe URL-ja e checkout-it është ajo ku ridrejtoni klientin. URL-ja bazë e API-t jepet bashkë me çelësat e sandbox-it — eksportojeni si PROTOCORE_API_BASE dhe thirrjet më poshtë funksionojnë saktësisht siç janë shkruar.
Krijoni porosinë
Një thirrje me shumën, monedhën dhe referencën tuaj. Çelësin e idempotencës e gjeneroni ju — një kërkesë e përsëritur kthen porosinë origjinale në vend që të krijojë një të dytë.
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"
}'Dërgoni klientin te checkout-i
Përgjigjja përmban një URL checkout-i në hostin tuaj të checkout-it — atë që jepet me sandbox-in, ose domenin tuaj sapo ta drejtoni te ne. Ridrejtoni te ajo, ose hapeni në SDK; në atë faqe ndodhen metodat, portofolet dhe 3-D Secure, kështu që nuk ka asgjë për të ndërtuar nga ana juaj.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Verifikoni rezultatin e nënshkruar
Kur pagesa përfundon, te endpoint-i juaj mbërrin një event i nënshkruar. Verifikoni nënshkrimin me webhook secret-in tuaj përpara se t'i besoni çfarëdo, pastaj përmbushni porosinë sipas referencës që e njihni tashmë.
{
"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
Endpoint-et që do të përdorni realisht.
Ka më shumë në dokumentacion, por ky është grupi përtej të cilit shumica e integrimeve nuk shkojnë.
Webhooks
Çfarë dëgjon backend-i juaj.
Çdo event mbart referencën e porosisë që krijuat, kështu handler-i juaj mund të jetë një switch mbi tipin dhe një kërkim nga ana juaj.
Kontrolloni nënshkrimin para se t'i besoni trupit.
Çdo dërgim mbart një vulë kohore dhe një nënshkrim HMAC mbi trupin e papërpunuar. Krahasoni në kohë konstante, refuzoni çdo gjë më të vjetër se dritarja juaj e tolerancës dhe trajtojeni një id eventi të dyfishtë si të përpunuar tashmë — ne riprovojmë te përgjigjet jo-2xx, ndaj handler-i juaj duhet të jetë 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;
}Garanci
Vetitë mbi të cilat mund të ndërtoni.
Krijime idempotente
Çdo krijim porosie pranon një çelës idempotence. Një kërkesë e përsëritur — pas një timeout-i, një deploy-i ose ridërgimi nga radha — kthen porosinë origjinale në vend që të tarifojë dy herë.
Evente të nënshkruara, të mbrojtura nga riprodhimi
Webhooks mbartin një nënshkrim HMAC me vulë kohore dhe një id eventi të qëndrueshëm. Dërgimet riprovohen me backoff derisa endpoint-i juaj të përgjigjet 2xx, kështu që një dritare deploy-i nuk humb asnjë pagesë.
Një referencë, nga fillimi në fund
Referenca që jepni gjatë krijimit shfaqet te checkout-i, fatura, webhook-u, pagesa dalëse dhe çdo rimbursim i mëvonshëm. Nuk ka identifikues të dytë për t'u përputhur mes sistemeve.
Modaliteti test është i njëjti rrugëtim kodi
Çelësat test ekzekutojnë të njëjtat rrjedha mbi sesione testimi. Ajo që kalon në test është ajo që del live — dallimi është cilët çelësa dërgoni, jo cilat endpoint-e thirrni.
Të dhëna testimi
Si t'i provoni rrugët që kanë rëndësi.
Pas çdo rruge më poshtë qëndron një kartë testimi, e listuar bashkë me çelësat kur lëshohet sandbox-i — numrat janë për çdo sandbox veç e veç dhe nuk publikohen këtu, që të mbeten të saktë kur ndryshojnë diapazonet e testimit të skemave. Sjellja është përcaktuese në të dyja rastet: një test verifikon një refuzim po aq lehtë sa një sukses.
Merr çelësat dhe fillo.
Një tregtar sandbox me çelësa API, sekrete webhook dhe çdo metodë të aktivizuar — plus dokumentimin e plotë, që ekipi yt të integrojë përpara se të nënshkruhet çdo gjë.