Arendajatele
Kolm päringut ja üks webhook.
Gateway on hostitud checkout, seega on integratsioon teadlikult väike: loo tellimus, suuna klient lehele, kontrolli allkirjastatud tulemust. Kogu liides on allpool — makseliides, makseviiside loogika, 3-D Secure, rahakotid ja kviitungid on meie ehitada ja ajakohasena hoida.
Ülevaade
Mille vastu sa integreerid.
- REST üle HTTPS
- JSON sisse, JSON välja
- Bearer API-võtmed
- Idempotentsivõtmed
- Allkirjastatud webhookid
- Kordusrünnete kaitse
- Test- ja live-režiim
- iOS-i ja Androidi SDK-d
- E-poe pluginad
- Manustatavad väljad
Kiirstart
Tühjalt tasutud tellimuseni.
Kogu õnnelik tee. Summad on väikseimates rahaühikutes, viited on sinu omad ja checkout URL on aadress, kuhu klient suunatakse. API baas-URL antakse koos sandboxi võtmetega — ekspordi see muutujana PROTOCORE_API_BASE ja allolevad päringud töötavad täpselt nii, nagu kirjas.
Loo tellimus
Üks päring summa, valuuta ja sinu enda viitega. Idempotentsivõtme genereerid sina — korratud päring tagastab algse tellimuse, mitte ei loo teist.
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"
}'Suuna klient checkouti
Vastuses on checkout URL sinu enda checkout-hostil — sandboxiga antud hostil või sinu enda domeenil, kui oled selle meie poole suunanud. Suuna klient sinna või ava see SDK-s; just sellel lehel asuvad makseviisid, rahakotid ja 3-D Secure, nii et sinu poolel pole midagi ehitada.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Kontrolli allkirjastatud tulemust
Kui makse on lõpule jõudnud, saabub sinu lõpp-punkti allkirjastatud sündmus. Kontrolli allkirja oma webhooki saladuse vastu enne, kui midagi usaldad, ja täida tellimus sulle juba tuntud viite järgi.
{
"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" }
}
}Viide
Lõpp-punktid, mida päriselt kasutad.
Dokumentatsioonis on rohkem, aga enamik integratsioone ei vaja midagi peale selle komplekti.
Webhookid
Millest sinu backend teada saab.
Iga sündmus kannab sinu loodud tellimuse viidet, nii et sinu töötleja võib olla lihtsalt switch sündmuse tüübi järgi ja otsing sinu enda andmetest.
Kontrolli allkirja enne, kui sisu usaldad.
Iga saadetis sisaldab ajatemplit ja toorkeha HMAC-allkirja. Võrdle konstantses ajas, lükka tagasi kõik, mis on vanem kui sinu lubatud aken, ja käsitle korduvat sündmuse id-d kui juba töödeldut — kordame saatmist iga mitte-2xx vastuse korral, seega peab ka sinu töötleja olema idempotentne.
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;
}Garantiid
Omadused, mille peale saad ehitada.
Idempotentne loomine
Iga tellimuse loomine nõuab idempotentsivõtit. Korratud päring — pärast timeouti, deploy'd või järjekorra uuesti edastamist — tagastab algse tellimuse, mitte ei tasu kaks korda.
Allkirjastatud, kordusrünnete vastu kaitstud sündmused
Webhookid kannavad ajatempliga HMAC-allkirja ja püsivat sündmuse id-d. Saatmist korratakse kasvava viivitusega, kuni sinu lõpp-punkt vastab 2xx, nii et deploy-aken ei kaota ühtegi makset.
Üks viide algusest lõpuni
Loomisel antud viide kuvatakse checkoutis, kviitungil, webhookis, väljamaksel ja hilisemal tagasimaksel. Süsteemide vahel pole vaja kaardistada teist identifikaatorit.
Testrežiim kasutab sama kooditeed
Testvõtmed käivitavad samu vooge testsessioonidel. Mis testis läbi läheb, see ka toodangusse jõuab — vahe on selles, milliseid võtmeid saadad, mitte selles, milliseid lõpp-punkte kutsud.
Testandmed
Kuidas olulisi teid läbi proovida.
Iga allolev stsenaarium põhineb testkaardil, mille leiad koos võtmetega sandboxi väljastamisel. Numbrid on sandboxi-põhised ja neid siin ei avaldata, nii et need jäävad õigeks ka siis, kui skeemide testvahemikud muutuvad. Käitumine on igal juhul deterministlik: test kontrollib keeldumist sama lihtsalt kui õnnestumist.
Hangi võtmed ja alusta.
Sandboxi kaupmees koos API võtmete, webhooki saladuste ja kõigi sisselülitatud meetoditega — lisaks täielik viitedokumentatsioon, et teie meeskond saaks integreerida enne, kui midagi on allkirjastatud.