Trei apeluri și un webhook.
Gateway este un checkout găzduit, așa că integrarea e intenționat mică: creezi o comandă, trimiți clientul către pagină, verifici rezultatul semnat. Tot ce urmează e toată suprafața — interfața de plată, logica metodelor, 3-D Secure, wallet-urile și chitanțele rămân ale noastre de construit și de ținut la zi.
Cu ce integrezi, de fapt.
- REST peste HTTPS
- JSON la intrare, JSON la ieșire
- Chei de API Bearer
- Chei de idempotență
- Webhook-uri semnate
- Protecție la reluare
- Mod de test și de producție
- SDK-uri iOS și Android
- Plugin-uri de magazin
- Câmpuri integrate
De la nimic la o comandă plătită.
Tot traseul fericit. Sumele sunt în unități minore, referințele sunt ale tale, iar URL-ul de checkout e cel către care redirecționezi clientul. URL-ul de bază al API-ului se emite odată cu cheile tale de sandbox — îl exporți ca PROTOCORE_API_BASE și apelurile de mai jos rulează exact așa cum sunt scrise.
Creezi comanda
Un singur apel cu suma, moneda și propria ta referință. Cheia de idempotență o generezi tu — o cerere reîncercată întoarce comanda originală în loc să creeze una a doua.
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"
}'Trimiți clientul la checkout
Răspunsul poartă un URL de checkout pe propria ta gazdă de checkout — cea emisă cu sandboxul tău sau domeniul tău, odată ce îl îndrepți către noi. Redirecționezi către el sau îl deschizi în SDK; pagina aceea e locul unde stau metodele, wallet-urile și 3-D Secure, deci nu ai nimic de construit de partea ta.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Verifici rezultatul semnat
Când plata se finalizează, un eveniment semnat ajunge la endpointul tău. Verifici semnătura cu secretul tău de webhook înainte să crezi orice, apoi livrezi pe referința pe care o știi deja.
{
"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" }
}
}Endpointurile pe care chiar le vei folosi.
În documentație sunt mai multe, dar ăsta e setul dincolo de care cele mai multe integrări nu cresc niciodată.
Ce află backendul tău.
Fiecare eveniment poartă referința de comandă pe care ai creat-o, așa că handlerul tău poate fi un switch pe tip și o căutare la tine.
Verifică semnătura înainte să crezi corpul.
Fiecare livrare poartă un timestamp și o semnătură HMAC peste corpul brut. Compară în timp constant, respinge orice e mai vechi decât fereastra ta de toleranță și tratează un id de eveniment duplicat ca deja procesat — reîncercăm la răspunsuri non-2xx, deci handlerul tău ar trebui să fie și el idempotent.
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;
// Respinge reluările din afara unei ferestre de cinci minute.
return Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}Proprietățile pe care poți construi.
Creări idempotente
Fiecare creare de comandă acceptă o cheie de idempotență. O cerere reîncercată — după un timeout, o lansare sau o redistribuire din coadă — întoarce comanda originală, nu o a doua încasare.
Evenimente semnate, protejate la reluare
Webhook-urile poartă o semnătură HMAC cu timestamp și un id stabil de eveniment. Livrările se reîncearcă cu backoff până când endpointul tău răspunde 2xx, așa că o fereastră de deploy nu pierde o plată.
O referință, cap-coadă
Referința pe care o dai la creare apare pe checkout, pe chitanță, în webhook, în virare și în orice rambursare ulterioară. Nu există un al doilea identificator de mapat între sisteme.
Modul de test e același traseu de cod
Cheile de test rulează fluxuri identice pe sesiuni de test. Ce trece în test e ce ajunge în producție — diferența e ce chei trimiți, nu ce endpointuri apelezi.
Cum exersezi traseele care contează.
Fiecare traseu de mai jos are în spate un card de test, listat împreună cu cheile tale când se emite sandboxul — numerele sunt per sandbox, nu publicate aici, ca să rămână corecte pe măsură ce intervalele de test ale schemelor se schimbă. Comportamentul e determinist oricum: un test verifică un refuz la fel de ușor ca o reușită.
Ia chei și pornește.
Un comerciant de test cu chei de API, secrete de webhook și fiecare metodă activată — plus referința completă, ca echipa ta să integreze înainte să se semneze ceva.
Cere acces la sandbox