Démarrage rapide

1. Intégrer le configurateur

Ajoutez le script et l’élément à la page produit, avec votre clé publique (pk_live_…, ou une clé de test pk_test_… pendant le développement). L’origine de la page doit figurer parmi les origines autorisées de la clé. L’intégration appelle ensuite elle-même GET /cfg/v1/config/public, POST /cfg/v1/preview, POST /cfg/v1/quote et POST /cfg/v1/order.

Quand le client commande, le service enregistre la commande signée et l’élément déclenche l’événement navigateur cutoptim:order avec { orderId, order, idempotencyKey }. Considérez cet événement comme une indication pour votre page, jamais comme la preuve d’un prix.

<script type="module" src="https://cfg.cutoptim.com/embed/assets/cutoptim-configurator.js"></script>

<button data-cutoptim-open="#cut">…</button>
<cutoptim-configurator id="cut" mode="modal" key="pk_live_your_publishable_key" lang="fr">
</cutoptim-configurator>

<script>
  document.getElementById('cut').addEventListener('cutoptim:order', (e) => {
    // e.detail = { orderId, order, idempotencyKey } - send it to YOUR server, which verifies it
  });
</script>

2. Vérifier sur votre serveur avant le panier

Votre serveur envoie le jeton de devis à POST /cfg/v1/quote/verify avec la clé secrète. La réponse contient valid et redeemed ; un refus reste un 200 avec valid: false et un reason. Il retrouve ensuite la commande désignée par le navigateur avec GET /cfg/v1/orders/{id} et compare le hash du plan, le hash du devis, la devise et les totaux avec le jeton vérifié. C’est seulement alors qu’il crée la ligne de panier, au prix vérifié.

curl -X POST https://cfg.cutoptim.com/cfg/v1/quote/verify \
  -H "Authorization: Bearer $CUTOPTIM_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"quoteToken":"<order.quote.quoteToken>"}'
# {"valid":true,"redeemed":true,"claims":{…},"test":false}

curl https://cfg.cutoptim.com/cfg/v1/orders/<orderId> \
  -H "Authorization: Bearer $CUTOPTIM_API_SECRET"
# {"orderId":"…","status":"received","priced":true,"planHash":"…","quoteHash":"…","totals":{…}}

3. Recevoir le webhook signé

Publiez un endpoint de webhook dans la configuration de votre boutique. Chaque commande réelle envoie order.created, chaque changement de statut order.status_changed. Lisez le corps brut, vérifiez l’en-tête CutOptim-Signature, puis enregistrez la commande une seule fois par CutOptim-Event-Id. Le récepteur ci-dessous est l’exemple de référence, tel quel.

// example-server.mjs - a webhook endpoint on node:http, to read and adapt.   CUTOPTIM_WEBHOOK_SIGNING=whsec_... node example-server.mjs
// (whsec_REPLACE_ME is a placeholder: the real secret comes from the CutOptim admin route.)
import { createServer } from 'node:http';
import { createWebhookReceiver } from './cutoptim-verify.mjs';

const secret = process.env.CUTOPTIM_WEBHOOK_SIGNING;
if (!secret) { console.error('set CUTOPTIM_WEBHOOK_SIGNING (whsec_REPLACE_ME is a placeholder)'); process.exit(1); }

const receive = createWebhookReceiver({
  secrets: [secret],
  async onEvent(event) {
    // event.type === 'order.created'; event.data.order is the signed order document. Store it in YOUR order table here,
    // keyed by event.data.orderId, in the same transaction that records the event id as seen.
    console.log('order.created', event.data.orderId);
  },
});

createServer(async (req, res) => {
  if (req.method !== 'POST') { res.writeHead(405).end(); return; }
  const chunks = []; let size = 0;
  for await (const c of req) { size += c.length; if (size > 2_000_000) { res.writeHead(413).end(); return; } chunks.push(c); }
  const out = await receive({ rawBody: Buffer.concat(chunks), headers: req.headers });   // the RAW bytes, not parsed JSON
  res.writeHead(out.status, { 'Content-Type': 'application/json' }).end(JSON.stringify({ result: out.reason }));
}).listen(Number(process.env.PORT ?? 8787));

Suite

Clés, clés de test et origines : Clés et authentification. Le récepteur complet, la version PHP et le calendrier des nouvelles tentatives : Webhooks. Une version pas à pas pour votre propre plateforme : Boutique sur mesure ou ERP.