Żviluppaturi
Tliet sejħiet u webhook.
Gateway huwa checkout ospitat, għalhekk l-integrazzjoni hija żgħira apposta: oħloq ordni, ibgħat il-klijent fuq il-paġna, ivverifika r-riżultat iffirmat. Dak kollu t'hawn taħt huwa s-superfiċje kollha — l-UI tal-pagament, il-loġika tal-metodi, 3-D Secure, il-wallets u l-irċevuti aħna nibnuhom u nżommuhom aġġornati.
Fil-qosor
Dak li qed tintegra miegħu.
- REST fuq HTTPS
- JSON gewwa, JSON barra
- Ċwievet API Bearer
- Ċwievet ta' idempotenza
- Webhooks iffirmati
- Protezzjoni mir-replay
- Modi test u live
- SDKs għal iOS u Android
- Plugins għall-ħwienet
- Fields inkorporati
Quickstart
Minn xejn sa ordni mħallsa.
Il-mogħdija sħiħa tas-suċċess. L-ammonti huma f'unitajiet minuri, ir-referenzi huma tiegħek, u l-URL tal-checkout huwa dak li lejh tirredirezzja l-klijent. L-URL bażi tal-API jinħareġ mal-ċwievet tas-sandbox tiegħek — esportah bħala PROTOCORE_API_BASE u s-sejħiet t'hawn taħt jaħdmu eżattament kif miktuba.
Oħloq l-ordni
Sejħa waħda bl-ammont, il-munita u r-referenza tiegħek. Iċ-ċavetta ta' idempotenza int tiġġenerha — talba li terġa' tintbagħat terġa' tagħti l-ordni oriġinali minflok toħloq it-tieni waħda.
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"
}'Ibgħat il-klijent fuq il-checkout
It-tweġiba ġġorr URL tal-checkout fuq il-host tiegħek stess — dak maħruġ mas-sandbox, jew id-dominju tiegħek stess malli tindirizzah lejna. Irredirezzja lejh, jew iftaħha fl-SDK; f'dik il-paġna jgħixu l-metodi, il-wallets u 3-D Secure, mela ma hemm xejn x'tibni min-naħa tiegħek.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Ivverifika r-riżultat iffirmat
Meta l-pagament jitlesta, avveniment iffirmat jasal fl-endpoint tiegħek. Ivverifika l-firma mal-webhook secret tiegħek qabel ma temmen xi ħaġa, imbagħad wettaq l-ordni skont ir-referenza li diġà taf.
{
"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" }
}
}Referenza
L-endpoints li tabilħaqq se tuża.
Hemm aktar fid-dokumentazzjoni, imma dan huwa s-sett li l-biċċa l-kbira tal-integrazzjonijiet qatt ma jaqbżu.
Webhooks
Dak li l-backend tiegħek jisma' dwaru.
Kull avveniment iġorr ir-referenza tal-ordni li ħlaqt int, biex il-handler tiegħek ikun bżonn biss switch fuq it-tip u tfittxija min-naħa tiegħek.
Iċċekkja l-firma qabel ma temmen il-body.
Kull konsenja ġġorr timestamp u firma HMAC fuq il-body mhux ipproċessat. Qabbel f'ħin kostanti, irrifjuta kull ma hu eqdem mit-tolleranza tiegħek, u ittratta id ta' avveniment duplikat bħala diġà mmaniġġjat — nirriprovaw fuq risposti mhux 2xx, għalhekk il-handler tiegħek għandu jkun idempotenti wkoll.
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;
}Garanziji
Il-proprjetajiet li tistax tibni fuqhom.
Ħolqien idempotenti
Kull ħolqien ta' ordni jieħu ċavetta ta' idempotenza. Talba li terġa' tintbagħat — wara timeout, deploy jew konsenja mill-ġdid mill-queue — terġa' tagħti l-ordni oriġinali minflok iċċarġja darbtejn.
Avvenimenti ffirmati u protetti mir-replay
Il-webhooks iġorru firma HMAC b'timestamp u id stabbli tal-avveniment. Il-konsenji jerġgħu jiġu ppruvati b'backoff sakemm l-endpoint tiegħek iwieġeb 2xx, biex ħin ta' deploy ma jitlifx pagament.
Referenza waħda, minn tarf sa tarf
Ir-referenza li tagħti meta toħloq l-ordni tidher fuq il-checkout, fl-irċevuta, fil-webhook, fil-payout u f'kull rimborż aktar tard. Ma hemm l-ebda identifikatur ieħor x'tqabbel bejn is-sistemi.
Il-modalità test hija l-istess mogħdija tal-kodiċi
Iċ-ċwievet tat-test iħaddmu eżattament l-istess flussi fuq sessjonijiet tat-test. Dak li jgħaddi fit-test huwa dak li jinħareġ — id-differenza hija liema ċwievet tibgħat, mhux liema endpoints issejjaħ.
Data tat-test
Kif tipprova l-mogħdijiet li jiġu f'loku.
Kull triq hawn taħt għandha karta tat-test warajha, elenkata maċ-ċwievet tiegħek meta joħroġ is-sandbox — in-numri huma għal kull sandbox u mhumiex ippubblikati hawn, biex jibqgħu korretti hekk kif jinbidlu l-firxiet tat-test tal-iskemi. L-imġiba hija deterministika fiż-żewġ każijiet: test jasserixxi fuq rifjut daqskemm fuq suċċess.
Ħu ċ-ċwievet u ibda.
Merchant sandbox b'ċwievet API, secrets tal-webhook u kull metodu mixgħul — flimkien mar-referenza sħiħa, biex it-tim tiegħek jintegra qabel ma tiġi ffirmata xi ħaġa.