Sviluppatori
Tre chiamate e un webhook.
Gateway è un checkout ospitato, quindi l'integrazione è volutamente minima: crei un ordine, mandi il cliente alla pagina, verifichi il risultato firmato. Qui sotto trovi tutta la superficie di integrazione: interfaccia di pagamento, logica dei metodi, 3-D Secure, wallet e ricevute sono compito nostro, sia da sviluppare sia da mantenere aggiornati.
In sintesi
Cosa andrai a integrare.
- REST su HTTPS
- JSON in ingresso, JSON in uscita
- Chiavi API Bearer
- Chiavi di idempotenza
- Webhook firmati
- Protezione da replay
- Modalità test e live
- SDK iOS e Android
- Plugin per gli store
- Campi incorporati
Quickstart
Da zero a un ordine pagato.
Il percorso completo, nel caso ideale. Gli importi sono in unità minori, i riferimenti sono tuoi e l'URL di checkout è la destinazione del redirect del cliente. L'URL di base dell'API viene fornito insieme alle chiavi sandbox: esportalo come PROTOCORE_API_BASE e le chiamate qui sotto funzionano esattamente così come sono.
Crea l'ordine
Una sola chiamata con importo, valuta e il tuo riferimento. La chiave di idempotenza la generi tu: una richiesta ripetuta restituisce l'ordine originale invece di crearne un secondo.
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"
}'Manda il cliente al checkout
La risposta contiene un URL di checkout sul tuo host di checkout: quello fornito con la sandbox, oppure il tuo dominio una volta puntato verso di noi. Fai il redirect, oppure aprilo nell'SDK: su quella pagina vivono i metodi di pagamento, i wallet e il 3-D Secure, quindi da parte tua non c'è nulla da sviluppare.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Verifica il risultato firmato
Quando il pagamento si completa, un evento firmato arriva al tuo endpoint. Verifica la firma con il tuo webhook secret prima di fidarti di qualsiasi dato, poi evadi l'ordine in base al riferimento che già conosci.
{
"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" }
}
}Riferimento
Gli endpoint che userai davvero.
Nella documentazione c'è di più, ma questo è l'insieme oltre il quale la maggior parte delle integrazioni non va.
Webhook
Di cosa viene informato il tuo backend.
Ogni evento riporta il riferimento dell'ordine che hai creato, quindi il tuo handler può ridursi a uno switch sul tipo e a una ricerca sul tuo lato.
Controlla la firma prima di fidarti del body.
Ogni consegna contiene un timestamp e una firma HMAC calcolata sul body grezzo. Confronta in tempo costante, scarta tutto ciò che supera la tua finestra di tolleranza e considera già gestito un event id duplicato: riproviamo l'invio sulle risposte non 2xx, quindi anche il tuo handler dev'essere idempotente.
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;
}Garanzie
Le proprietà su cui puoi contare.
Creazioni idempotenti
Ogni creazione di ordine accetta una chiave di idempotenza. Una richiesta ripetuta, dopo un timeout, un deploy o una riconsegna dalla coda, restituisce l'ordine originale invece di addebitare due volte.
Eventi firmati e protetti da replay
I webhook riportano una firma HMAC con timestamp e un event id stabile. Le consegne vengono ritentate con backoff finché il tuo endpoint non risponde 2xx, quindi una finestra di deploy non fa perdere nessun pagamento.
Un solo riferimento, dall'inizio alla fine
Il riferimento che indichi alla creazione compare nel checkout, nella ricevuta, nel webhook, nel payout e in ogni rimborso successivo. Non c'è un secondo identificativo da mappare tra i sistemi.
La modalità test usa lo stesso codice
Le chiavi di test eseguono gli stessi identici flussi su sessioni di test. Ciò che passa in test è ciò che va in produzione: cambiano le chiavi che invii, non gli endpoint che chiami.
Dati di test
Come mettere alla prova i percorsi che contano.
Ogni percorso qui sotto ha dietro una carta di test, riportata insieme alle chiavi quando viene emessa la sandbox: i numeri sono specifici per ogni sandbox e non vengono pubblicati qui, così restano corretti anche quando cambiano i range di test dei circuiti. Il comportamento è comunque deterministico: un test può verificare un rifiuto con la stessa facilità di un'approvazione.
Ottieni le chiavi e inizia.
Un merchant sandbox con chiavi API, secret dei webhook e tutti i metodi attivi, più la documentazione completa, così il tuo team può integrare prima ancora di firmare.