Développeurs
Trois appels et un webhook.
Gateway est un checkout hébergé, l'intégration est donc volontairement réduite : créer une commande, envoyer le client vers la page, vérifier le résultat signé. Voilà toute la surface — l'interface de paiement, la logique des moyens de paiement, 3-D Secure, les wallets et les reçus, c'est à nous de les construire et de les maintenir à jour.
En bref
Ce que vous intégrez.
- REST sur HTTPS
- JSON en entrée, JSON en sortie
- Clés API Bearer
- Clés d'idempotence
- Webhooks signés
- Protection contre le rejeu
- Modes test et live
- SDK iOS & Android
- Plugins e-commerce
- Champs intégrés
Démarrage rapide
De zéro à une commande payée.
Le parcours nominal complet. Les montants sont en unités mineures, les références sont les vôtres, et l'URL de checkout est celle vers laquelle vous redirigez le client. L'URL de base de l'API est fournie avec vos clés sandbox — exportez-la dans PROTOCORE_API_BASE et les appels ci-dessous fonctionnent tels quels.
Créer la commande
Un seul appel avec le montant, la devise et votre propre référence. La clé d'idempotence, c'est à vous de la générer — une requête rejouée renvoie la commande d'origine au lieu d'en créer une seconde.
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"
}'Envoyer le client vers le checkout
La réponse contient une URL de checkout sur votre propre hôte de checkout — celui fourni avec votre sandbox, ou votre propre domaine une fois qu'il pointe vers nous. Redirigez le client vers cette URL, ou ouvrez-la dans le SDK ; c'est sur cette page que vivent les moyens de paiement, les wallets et 3-D Secure, il n'y a donc rien à développer de votre côté.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Vérifier le résultat signé
Une fois le paiement terminé, un événement signé arrive sur votre endpoint. Vérifiez la signature avec votre secret de webhook avant de faire confiance à quoi que ce soit, puis livrez en vous appuyant sur la référence que vous connaissez déjà.
{
"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" }
}
}Référence
Les endpoints que vous utiliserez vraiment.
La documentation va plus loin, mais ce sont ces endpoints que la plupart des intégrations ne dépassent jamais.
Webhooks
Ce que votre backend apprend.
Chaque événement porte la référence de commande que vous avez créée : votre handler peut se réduire à un switch sur le type et une recherche de votre côté.
Vérifiez la signature avant de faire confiance au corps.
Chaque envoi contient un horodatage et une signature HMAC calculée sur le corps brut. Comparez en temps constant, rejetez tout ce qui dépasse votre fenêtre de tolérance et considérez un id d'événement en double comme déjà traité — nous réessayons après toute réponse non-2xx, votre handler doit donc lui aussi être 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 propriétés sur lesquelles vous pouvez vous appuyer.
Créations idempotentes
Chaque création de commande accepte une clé d'idempotence. Une requête rejouée — après un timeout, un déploiement ou une relivraison de file — renvoie la commande d'origine au lieu de débiter deux fois.
Événements signés, protégés contre le rejeu
Les webhooks portent une signature HMAC horodatée et un id d'événement stable. Les envois sont retentés avec backoff jusqu'à ce que votre endpoint réponde 2xx : une fenêtre de déploiement ne fait donc perdre aucun paiement.
Une seule référence, de bout en bout
La référence que vous fournissez à la création apparaît sur le checkout, le reçu, le webhook, le versement et tout remboursement ultérieur. Aucun second identifiant à faire correspondre entre vos systèmes.
Le mode test emprunte le même code
Les clés de test exécutent exactement les mêmes flux sur des sessions de test. Ce qui passe en test est ce qui part en production — la différence tient aux clés que vous envoyez, pas aux endpoints que vous appelez.
Données de test
Comment exercer les parcours qui comptent.
Chaque scénario ci-dessous correspond à une carte de test, indiquée avec vos clés lors de la création de la sandbox — les numéros sont propres à chaque sandbox et ne sont pas publiés ici, afin de rester valides lorsque les plages de test des schemes évoluent. Le comportement est déterministe dans tous les cas : un test peut vérifier un refus aussi facilement qu'un succès.
Obtenez vos clés et lancez-vous.
Un marchand sandbox avec clés API, secrets de webhook et tous les moyens de paiement activés — plus la documentation complète, pour que votre équipe puisse intégrer avant toute signature.