Entwickler
Drei Calls und ein Webhook.
Gateway ist ein gehosteter Checkout, deshalb bleibt die Integration bewusst klein: Bestellung anlegen, Kunden auf die Seite leiten, das signierte Ergebnis prüfen. Mehr gibt es nicht — Zahlungsoberfläche, Zahlart-Logik, 3-D Secure, Wallets und Belege bauen und pflegen wir.
Überblick
Wogegen Sie integrieren.
- REST über HTTPS
- JSON rein, JSON raus
- Bearer-API-Keys
- Idempotency-Keys
- Signierte Webhooks
- Replay-Schutz
- Test- und Live-Modus
- iOS- & Android-SDKs
- Shop-Plugins
- Eingebettete Felder
Quickstart
Vom Nichts zur bezahlten Bestellung.
Der komplette Happy Path. Beträge stehen in der kleinsten Währungseinheit, Referenzen vergeben Sie selbst, und die Checkout-URL ist das Ziel für die Weiterleitung des Kunden. Die API-Basis-URL erhalten Sie mit Ihren Sandbox-Keys — exportieren Sie sie als PROTOCORE_API_BASE, und die Aufrufe unten laufen genau so, wie sie dastehen.
Bestellung anlegen
Ein Aufruf mit Betrag, Währung und Ihrer eigenen Referenz. Den Idempotency-Key generieren Sie selbst — eine wiederholte Anfrage liefert die ursprüngliche Bestellung zurück, statt eine zweite anzulegen.
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"
}'Kunden zum Checkout weiterleiten
Die Antwort enthält eine Checkout-URL auf Ihrem eigenen Checkout-Host — dem mit Ihrer Sandbox ausgestellten oder Ihrer eigenen Domain, sobald Sie sie auf uns zeigen lassen. Leiten Sie dorthin weiter oder öffnen Sie sie im SDK; auf dieser Seite liegen Zahlarten, Wallets und 3-D Secure, Sie müssen also nichts bauen.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Signiertes Ergebnis prüfen
Sobald die Zahlung abgeschlossen ist, erreicht ein signiertes Event Ihren Endpunkt. Prüfen Sie die Signatur gegen Ihr Webhook-Secret, bevor Sie irgendetwas vertrauen, und liefern Sie dann anhand der Referenz aus, die Sie bereits kennen.
{
"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" }
}
}Referenz
Die Endpunkte, die Sie wirklich brauchen.
Die Doku bietet mehr, aber über diese Auswahl wachsen die meisten Integrationen nie hinaus.
Webhooks
Wovon Ihr Backend erfährt.
Jedes Event trägt die Bestellreferenz, die Sie angelegt haben. Ihr Handler kann also ein Switch auf den Typ plus ein Lookup auf Ihrer Seite sein.
Signatur prüfen, bevor Sie dem Body vertrauen.
Jede Zustellung enthält einen Zeitstempel und eine HMAC-Signatur über den Raw Body. Vergleichen Sie in konstanter Zeit, verwerfen Sie alles, was älter als Ihr Toleranzfenster ist, und behandeln Sie doppelte Event-IDs als bereits verarbeitet — bei Antworten außerhalb von 2xx versuchen wir es erneut, Ihr Handler sollte also ebenfalls idempotent sein.
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;
}Garantien
Die Eigenschaften, auf die Sie bauen können.
Idempotente Anlage
Jede Bestellanlage nimmt einen Idempotency-Key entgegen. Eine wiederholte Anfrage — nach Timeout, Deploy oder erneuter Queue-Zustellung — liefert die ursprüngliche Bestellung zurück, statt doppelt zu belasten.
Signierte Events mit Replay-Schutz
Webhooks tragen eine HMAC-Signatur mit Zeitstempel und eine stabile Event-ID. Zustellungen werden mit Backoff wiederholt, bis Ihr Endpunkt mit 2xx antwortet — ein Deploy-Fenster kostet also keine Zahlung.
Eine Referenz, durchgängig
Die Referenz, die Sie beim Anlegen mitgeben, erscheint im Checkout, auf dem Beleg, im Webhook, im Payout und bei jeder späteren Erstattung. Eine zweite Kennung, die Sie zwischen Systemen abbilden müssten, gibt es nicht.
Der Testmodus nutzt denselben Codepfad
Test-Keys durchlaufen dieselben Abläufe gegen Testsitzungen. Was im Test funktioniert, geht live — der Unterschied liegt in den gesendeten Keys, nicht in den aufgerufenen Endpunkten.
Testdaten
So durchlaufen Sie die Pfade, auf die es ankommt.
Hinter jedem Pfad unten steht eine Testkarte, die mit Ihren Keys aufgeführt wird, sobald die Sandbox ausgestellt ist — die Nummern gelten pro Sandbox und stehen nicht hier, damit sie auch bei geänderten Test-Ranges der Schemes stimmen. Das Verhalten ist in jedem Fall deterministisch: Ein Test prüft eine Ablehnung genauso einfach wie einen Erfolg.
Keys holen und loslegen.
Ein Sandbox-Händlerkonto mit API-Keys, Webhook-Secrets und allen aktivierten Zahlungsmethoden — plus die vollständige Referenz, damit Ihr Team integrieren kann, bevor etwas unterschrieben ist.