Dla deweloperów
Trzy wywołania i webhook.
Gateway to hostowany checkout, więc integracja jest celowo niewielka: tworzysz zamówienie, kierujesz klienta na stronę, weryfikujesz podpisany wynik. Poniżej jest cała powierzchnia API — interfejs płatności, logika metod, 3-D Secure, portfele i potwierdzenia to nasza działka: budujemy je i na bieżąco aktualizujemy.
Zarys
Z czym się integrujesz.
- REST przez HTTPS
- JSON na wejściu, JSON na wyjściu
- Klucze API typu Bearer
- Klucze idempotentności
- Podpisane webhooki
- Ochrona przed atakami replay
- Tryb testowy i produkcyjny
- SDK na iOS i Android
- Wtyczki do sklepów
- Osadzane pola
Szybki start
Od zera do opłaconego zamówienia.
Cała ścieżka bez niespodzianek. Kwoty podajemy w najmniejszych jednostkach waluty, numer referencyjny nadajesz Ty, a adres URL checkoutu to ten, na który przekierowujesz klienta. Bazowy adres API dostajesz razem z kluczami sandboxa — wyeksportuj go jako PROTOCORE_API_BASE, a poniższe wywołania zadziałają dokładnie tak, jak je zapisano.
Utwórz zamówienie
Jedno wywołanie z kwotą, walutą i własnym numerem referencyjnym. Klucz idempotentności generujesz po swojej stronie — ponowione żądanie zwraca oryginalne zamówienie zamiast tworzyć drugie.
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"
}'Wyślij klienta do checkoutu
Odpowiedź zawiera adres URL checkoutu na Twoim hoście checkoutu — tym wydanym wraz z sandboxem albo na własnej domenie, gdy tylko skierujesz ją na nas. Przekieruj na niego klienta lub otwórz go w SDK; na tej stronie działają metody płatności, portfele i 3-D Secure, więc po Twojej stronie nie ma nic do budowania.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Zweryfikuj podpisany wynik
Gdy płatność się zakończy, na Twój endpoint trafi podpisane zdarzenie. Zanim czemukolwiek zaufasz, zweryfikuj podpis względem sekretu webhooka, a następnie zrealizuj zamówienie na podstawie znanego Ci numeru referencyjnego.
{
"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" }
}
}Referencja
Endpointy, z których faktycznie skorzystasz.
W dokumentacji jest tego więcej, ale to zestaw, poza który większość integracji nigdy nie wychodzi.
Webhooki
O czym dowiaduje się Twój backend.
Każde zdarzenie niesie numer referencyjny utworzonego zamówienia, więc Twój handler może sprowadzać się do switcha po typie i wyszukania po własnej stronie.
Sprawdź podpis, zanim zaufasz treści.
Każda dostawa niesie znacznik czasu i podpis HMAC liczony z surowej treści. Porównuj w stałym czasie, odrzucaj wszystko starsze niż Twoje okno tolerancji, a zduplikowany identyfikator zdarzenia traktuj jako już obsłużony — ponawiamy przy odpowiedziach innych niż 2xx, więc Twój handler też powinien być idempotentny.
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;
}Gwarancje
Właściwości, na których możesz budować.
Idempotentne tworzenie
Każde utworzenie zamówienia przyjmuje klucz idempotentności. Ponowione żądanie — po timeoucie, deployu czy ponownym dostarczeniu z kolejki — zwraca oryginalne zamówienie zamiast obciążyć dwukrotnie.
Podpisane zdarzenia z ochroną przed replay
Webhooki niosą podpis HMAC ze znacznikiem czasu i stały identyfikator zdarzenia. Dostawy są ponawiane z backoffem, aż Twój endpoint odpowie 2xx, więc okno wdrożenia nie zgubi płatności.
Jedna referencja, od początku do końca
Referencja podana przy tworzeniu pojawia się w checkoucie, potwierdzeniu, webhooku, wypłacie i każdym późniejszym zwrocie. Nie ma drugiego identyfikatora do mapowania między systemami.
Tryb testowy to ta sama ścieżka kodu
Klucze testowe uruchamiają identyczne przepływy na sesjach testowych. Co przechodzi w teście, trafia na produkcję — różni się tylko to, jakie klucze wysyłasz, a nie jakie endpointy wywołujesz.
Dane testowe
Jak przećwiczyć ścieżki, które mają znaczenie.
Za każdą ścieżką stoi karta testowa. Znajdziesz ją razem z kluczami, gdy wydamy sandbox — numery są przypisane do sandboxa, a nie publikowane tutaj, dzięki czemu pozostają poprawne, gdy zmieniają się testowe zakresy schematów kartowych. Zachowanie jest w obu przypadkach deterministyczne: test potwierdzi odrzucenie równie łatwo jak sukces.
Weź klucze i zaczynaj.
Sandbox merchant z kluczami API, sekretami webhooków i włączonymi wszystkimi metodami — plus pełna dokumentacja, by Twój zespół mógł zintegrować się, zanim cokolwiek zostanie podpisane.