Desenvolupadors
Tres crides i un webhook.
Gateway és un checkout allotjat, així que la integració és deliberadament petita: crees una comanda, envies el client a la pàgina i verifiques el resultat signat. Tot el que veus a continuació és la superfície completa: la interfície de pagament, la lògica dels mètodes, 3-D Secure, les wallets i els rebuts els construïm i els mantenim al dia nosaltres.
Com és
Amb què t'estàs integrant.
- REST sobre HTTPS
- JSON d'entrada, JSON de sortida
- Claus d'API Bearer
- Claus d'idempotència
- Webhooks signats
- Protecció contra repeticions
- Modes de prova i producció
- SDK per a iOS i Android
- Plugins per a botigues
- Camps incrustats
Quickstart
De zero a una comanda pagada.
Tot el camí feliç. Els imports van en unitats menors, les referències són teves i la URL del checkout és la que obres al client com a redirecció. La URL base de l'API s'emet amb les claus del sandbox: exporta-la com a PROTOCORE_API_BASE i les crides següents funcionen tal com estan escrites.
Crea la comanda
Una sola crida amb l'import, la divisa i la teva pròpia referència. La clau d'idempotència la generes tu: una petició reintentada retorna la comanda original en lloc de crear-ne una segona.
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"
}'Envia el client al checkout
La resposta inclou una URL de checkout al teu propi host de checkout: el que s'emet amb el sandbox, o el teu domini quan l'apuntis cap a nosaltres. Redirigeix-hi el client o obre-la amb l'SDK; aquesta pàgina concentra els mètodes, les wallets i 3-D Secure, així que no hi ha res a construir pel teu cantó.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Verifica el resultat signat
Quan el pagament es completa, un esdeveniment signat arriba al teu endpoint. Verifica la signatura amb el teu secret de webhook abans de fiar-te de res i, després, serveix la comanda segons la referència que ja coneixes.
{
"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" }
}
}Referència
Els endpoints que utilitzaràs de debò.
A la documentació hi ha més coses, però aquest és el conjunt del qual la majoria d'integracions mai no surten.
Webhooks
Del que s'assabenta el teu backend.
Cada esdeveniment porta la referència de la comanda que has creat, de manera que el teu handler pot reduir-se a un switch sobre el tipus i una cerca al teu cantó.
Comprova la signatura abans de fiar-te del cos.
Cada enviament porta un timestamp i una signatura HMAC sobre el cos en brut. Compara en temps constant, rebutja qualsevol cosa més antiga que la teva finestra de tolerància i tracta un id d'esdeveniment duplicat com a ja gestionat: reintentem davant de respostes no 2xx, així que el teu handler també ha de ser 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;
// Reject replays outside a five-minute window.
return Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}Garanties
Les propietats sobre les quals pots construir.
Creacions idempotents
Cada creació de comanda admet una clau d'idempotència. Una petició reintentada, després d'un timeout, un desplegament o una redelivery de la cua, retorna la comanda original en lloc de cobrar dues vegades.
Esdeveniments signats i protegits contra repeticions
Els webhooks porten una signatura HMAC amb timestamp i un id d'esdeveniment estable. Els enviaments es reintenten amb backoff fins que el teu endpoint respongui 2xx, de manera que una finestra de desplegament no fa perdre cap pagament.
Una sola referència, de punta a punta
La referència que aportes en crear la comanda apareix al checkout, al rebut, al webhook, al payout i en qualsevol reemborsament posterior. No hi ha cap segon identificador per mapar entre sistemes.
El mode de prova segueix el mateix camí de codi
Les claus de prova executen exactament els mateixos fluxos sobre sessions de prova. El que passa a prova és el que arriba a producció: la diferència és quines claus envies, no quins endpoints crides.
Dades de prova
Com exercitar els camins que importen.
Cada camí d'aquí sota té al darrere una targeta de prova, que trobaràs amb les claus quan s'emeti el sandbox. Els números són per sandbox i no es publiquen aquí, perquè continuïn sent correctes quan canviïn els rangs de prova dels schemes. El comportament és determinista en tots els casos: un test pot verificar un rebuig igual de fàcilment que una aprovació.
Aconsegueix les claus i comença.
Un comerç sandbox amb claus d'API, secrets de webhook i tots els mètodes activats, a més de la referència completa, perquè el teu equip pugui integrar abans de signar res.