Developers
Drie calls en een webhook.
Gateway is een gehoste checkout, dus de integratie is bewust klein: maak een order aan, stuur de klant naar de pagina, verifieer het ondertekende resultaat. Dit is het hele oppervlak — de betaal-UI, de methodelogica, 3-D Secure, wallets en bonnen bouwen en onderhouden wij.
Opzet
Waartegen je integreert.
- REST over HTTPS
- JSON in, JSON uit
- Bearer API-keys
- Idempotency-keys
- Ondertekende webhooks
- Replay-beveiliging
- Test- en livemodus
- iOS & Android SDK's
- Webshop-plugins
- Embedded velden
Quickstart
Van niets naar een betaalde order.
Het hele happy path. Bedragen staan in kleinste eenheden, referenties zijn van jou en de checkout-URL is waar je de klant naartoe stuurt. De API-basis-URL krijg je bij je sandbox-keys — exporteer hem als PROTOCORE_API_BASE en de calls hieronder werken precies zoals ze er staan.
De order aanmaken
Eén call met het bedrag, de valuta en je eigen referentie. De idempotency key genereer je zelf — een herhaald verzoek geeft de oorspronkelijke order terug in plaats van een tweede aan te maken.
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"
}'De klant naar de checkout sturen
Het antwoord bevat een checkout-URL op je eigen checkout-host — die van je sandbox, of je eigen domein zodra je dat naar ons laat wijzen. Stuur de klant erheen door, of open de URL in de SDK; op die pagina zitten de methoden, de wallets en 3-D Secure, dus aan jouw kant hoef je niets te bouwen.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Het ondertekende resultaat verifiëren
Zodra de betaling is voltooid, komt er een ondertekend event binnen op je endpoint. Verifieer de handtekening met je webhook secret voordat je iets vertrouwt, en handel daarna af op de referentie die je al kent.
{
"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" }
}
}Referentie
De endpoints die je echt gebruikt.
In de docs staat meer, maar dit is de set waar de meeste integraties nooit overheen groeien.
Webhooks
Waar je backend van hoort.
Elk event bevat de orderreferentie die je hebt aangemaakt, dus je handler kan een switch op het type zijn plus een lookup aan jouw kant.
Controleer de handtekening voordat je de body vertrouwt.
Elke levering bevat een timestamp en een HMAC-handtekening over de ruwe body. Vergelijk in constante tijd, weiger alles wat ouder is dan je tolerantievenster en beschouw een dubbel event-id als al verwerkt — bij non-2xx-antwoorden proberen we opnieuw, dus ook je handler moet idempotent zijn.
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;
}Garanties
De eigenschappen waarop je kunt bouwen.
Idempotente creates
Elke ordercreatie neemt een idempotency key mee. Een herhaald verzoek — na een timeout, een deploy of een herlevering uit de queue — geeft de oorspronkelijke order terug in plaats van dubbel te belasten.
Ondertekende events met replay-beveiliging
Webhooks bevatten een HMAC-handtekening met timestamp en een stabiel event-id. Leveringen worden met backoff herhaald totdat je endpoint met 2xx antwoordt, zodat een deploy-venster geen betaling kost.
Eén referentie, van begin tot eind
De referentie die je bij het aanmaken meegeeft, staat op de checkout, de bon, de webhook, de payout en elke latere terugbetaling. Er is geen tweede identifier om tussen systemen te mappen.
Testmodus gebruikt hetzelfde codepad
Testkeys doorlopen dezelfde flows tegen testsessies. Wat in test slaagt, gaat live — het verschil zit in welke keys je meestuurt, niet in welke endpoints je aanroept.
Testdata
Zo test je de paden die ertoe doen.
Achter elk pad hieronder zit een testkaart. Je ontvangt die samen met je keys zodra de sandbox is aangemaakt. De nummers gelden per sandbox en staan hier niet gepubliceerd, zodat ze kloppen wanneer de testreeksen van de card schemes veranderen. Het gedrag is in beide gevallen deterministisch: een test kan net zo makkelijk op een afwijzing asserten als op een succes.
Haal je keys op en begin.
Een sandbox-merchant met API-keys, webhook-secrets en alle methoden ingeschakeld — plus de volledige referentie, zodat jullie team kan integreren voordat er iets is getekend.