Izstrādātājiem
Trīs izsaukumi un webhook.
Gateway ir hostēta checkout lapa, tāpēc integrācija ir apzināti neliela: izveido pasūtījumu, nosūti klientu uz lapu, pārbaudi parakstīto rezultātu. Tas ir viss, kas jums jāintegrē — maksājumu saskarni, metožu loģiku, 3-D Secure, makus un kvītis veidojam un uzturam aktuālus mēs.
Kopaina
Ar ko jūs integrējaties.
- REST pār HTTPS
- JSON ienāk, JSON iziet
- Bearer API atslēgas
- Idempotences atslēgas
- Parakstīti webhook
- Aizsardzība pret atkārtošanu
- Test un live režīmi
- iOS & Android SDK
- Veikalu spraudņi
- Iegultie lauki
Ātrais starts
No nulles līdz apmaksātam pasūtījumam.
Viss veiksmīgais scenārijs. Summas ir mazākajās vienībās, atsauces nosaka jūs, un checkout URL ir adrese, uz kuru novirzāt klientu. API bāzes URL tiek izsniegts kopā ar sandbox atslēgām — eksportējiet to kā PROTOCORE_API_BASE, un zemāk redzamie izsaukumi darbosies tieši tā, kā uzrakstīti.
Izveido pasūtījumu
Viens izsaukums ar summu, valūtu un jūsu pašu atsauci. Idempotences atslēgu ģenerējat jūs — atkārtots pieprasījums atgriež sākotnējo pasūtījumu, nevis izveido otru.
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"
}'Nosūti klientu uz checkout
Atbildē ir checkout URL uz jūsu checkout resursdatora — tā, kas izsniegts kopā ar sandbox, vai uz jūsu domēnu, kad to novirzāt uz mums. Novirziet klientu uz to vai atveriet SDK; tieši šajā lapā darbojas metodes, maki un 3-D Secure, tāpēc jūsu pusē nekas nav jābūvē.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Pārbaudi parakstīto rezultātu
Kad maksājums ir pabeigts, uz jūsu endpoint tiek nosūtīts parakstīts notikums. Pirms kam uzticēties, pārbaudiet parakstu ar savu webhook noslēpumu, tad izpildiet pasūtījumu pēc atsauces, kas jums jau ir zināma.
{
"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" }
}
}Atsauce
Endpointi, ko jūs tiešām izmantosiet.
Dokumentācijā ir vairāk, taču lielākā daļa integrāciju nekad neiziet ārpus šī kopuma.
Webhook
Par ko uzzina jūsu backend.
Katrs notikums satur jūsu izveidoto pasūtījuma atsauci, tāpēc jūsu apstrādātājs var būt vienkāršs switch pēc tipa un meklēšana jūsu pusē.
Pārbaudiet parakstu, pirms uzticaties saturam.
Katrs sūtījums satur laikspiedolu un HMAC parakstu pār neapstrādāto saturu. Salīdziniet nemainīgā laikā, noraidiet visu, kas vecāks par jūsu pieļauto logu, un dublētu notikuma id uzskatiet par jau apstrādātu — mēs mēģinām atkārtoti pēc atbildēm, kas nav 2xx, tāpēc arī jūsu apstrādātājam jābūt idempotentam.
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;
}Garantijas
Īpašības, uz kurām varat balstīties.
Idempotenta izveide
Katrs pasūtījuma izveides izsaukums pieņem idempotences atslēgu. Atkārtots pieprasījums — pēc taimauta, deploy vai rindas atkārtotas piegādes — atgriež sākotnējo pasūtījumu, nevis iekasē maksu divreiz.
Parakstīti notikumi ar aizsardzību pret atkārtošanu
Webhook satur HMAC parakstu ar laikspiedolu un stabilu notikuma id. Piegādes tiek atkārtotas ar pieaugošu aizturi, līdz jūsu endpoint atbild ar 2xx, tāpēc deploy laikā neviens maksājums netiek pazaudēts.
Viena atsauce no sākuma līdz beigām
Atsauce, ko norādāt izveidojot, parādās checkout lapā, kvītī, webhook, izmaksā un jebkurā vēlākā atmaksā. Nav otra identifikatora, ko jāsaista starp sistēmām.
Test režīmā darbojas tas pats kods
Test atslēgas palaiž identiskas plūsmas pret test sesijām. Kas iet cauri testā, to arī izlaižat produkcijā — atšķirība ir tikai tajā, kuras atslēgas sūtāt, nevis kurus endpoint izsaucat.
Testa dati
Kā pārbaudīt svarīgākos scenārijus.
Katram no tālāk aprakstītajiem scenārijiem ir sava testa karte — tās tiek norādītas kopā ar atslēgām, kad tiek izsniegta sandbox vide. Numuri ir atsevišķi katrai sandbox videi, nevis publicēti šeit, tāpēc tie paliek derīgi, mainoties shēmu testa diapazoniem. Uzvedība abos gadījumos ir deterministiska: tests var pārbaudīt gan atteikumu, gan veiksmīgu darījumu.
Saņem atslēgas un sāc.
Sandbox tirgotājs ar API atslēgām, webhook noslēpumiem un visām ieslēgtām metodēm — kā arī pilna dokumentācija, lai jūsu komanda varētu integrēt vēl pirms jebkā parakstīšanas.