API Preznt

Mis à jour le 14 octobre 2026

Émettez des cartes cadeaux Preznt depuis votre site, votre caisse ou vos outils, et encaissez-les. JSON, HTTPS, une clé secrète par commerce.

Authentification

Créez une clé dans votre espace pro (Intégrations). Envoyez-la côté serveur uniquement, jamais depuis un navigateur ou une application mobile.

curl https://preznt.fr/api/v1/ping \
  -H "Authorization: Bearer pz_sk_..."

Émettre une carte cadeau

Après une vente payée sur votre site. Le client reçoit sa carte par e-mail (sauf send_email: false) et la retrouve dans son espace Preznt pour l’offrir. L’en-tête Idempotency-Key évite les doublons si vous réessayez.

curl https://preznt.fr/api/v1/vouchers \
  -H "Authorization: Bearer pz_sk_..." \
  -H "Idempotency-Key: commande-1234-ligne-1" \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 5000, "buyer_email": "client@exemple.fr", "merchant_code": "CAISSE-00042", "external_ref": "1234" }'

Réponse (201, ou 200 si la clé d’idempotence a déjà servi) :

{ "order": { "id": "ord_...", "amount_cents": 5000, "fee_cents": 300, ... },
  "vouchers": [{ "id": "vch_...", "code": "PZ-7DVC-T9A3-K4NP", "merchant_code": "CAISSE-00042",
                 "amount_cents": 5000, "balance_cents": 5000, "expires_on": "2027-10-14", "status": "active" }] }

amount_cents (requis) : de 100 à 500 000. quantity : 1 à 20.
buyer_email (requis), product_id, expires_on (AAAA-MM-JJ), merchant_code (votre numéro de caisse, unique chez vous), external_ref, recipient_name, message, channel (api, woocommerce, shopify, prestashop).

Consulter et encaisser

GET  https://preznt.fr/api/v1/vouchers?code=PZ-7DVC-T9A3-K4NP     # ou votre code de caisse
GET  https://preznt.fr/api/v1/vouchers/vch_...                    # détail + historique
POST https://preznt.fr/api/v1/vouchers/vch_.../redeem   { "amount_cents": 2000, "reference": "ticket 881" }
POST https://preznt.fr/api/v1/redemptions/red_.../void            # annule un encaissement
POST https://preznt.fr/api/v1/vouchers/vch_.../void               # annule une carte jamais utilisée (remboursement)
GET  https://preznt.fr/api/v1/products                            # vos cartes en vente

L’encaissement partiel est possible ; le solde restant est conservé. Deux encaissements simultanés ne peuvent pas dépenser deux fois le même solde.

Erreurs

{ "error": { "code": "insufficient_balance", "message": "Solde insuffisant : il reste 12,00 €." } }

Codes fréquents : authentication_required, invalid_api_key, invalid_request, voucher_not_found, invalid_code (faute de frappe détectée), ambiguous_merchant_code, voucher_expired, voucher_empty, insufficient_balance.

Webhooks

Événements : order.paid, voucher.issued, voucher.sent, voucher.opened, voucher.redeemed, voucher.voided, redemption.voided. Chaque envoi porte Preznt-Signature: t=…,v1=… : vérifiez HMAC-SHA256(secret, t + "." + corps brut) et refusez les horodatages de plus de 5 minutes.

// Node.js
const [t, v1] = header.split(',').map((p) => p.split('=')[1]);
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Date.now() / 1000 - Number(t) < 300;

Répondez 2xx en moins de 8 secondes. Sinon, Preznt réessaie avec un délai croissant pendant 24 heures.

Commission

Les cartes émises par l’API sont payées sur votre site : la commission de votre formule est facturée le 1er du mois suivant. Les ventes sur votre vitrine Preznt sont prélevées directement au paiement.