Documentation développeurs

Quelques lignes. Et vous encaissez.

API REST simple. Webhooks signés HMAC-SHA256. Idempotency keys. SDK pour les langages courants. Test mode complet avec faucet de test. Documentation pensée pour qu'un développeur compétent intègre en moins d'une heure.

Quick start

Cinq minutes. Une facture.

Créez votre première facture de test sans même configurer de wallet. SVRNG Pay vous fournit une xpub de test au signup pour expérimenter avant de connecter votre vrai wallet.

// 1. Authentifiez-vous avec votre clé de test (sp_test_...)
const SVRNG_PAY_KEY = process.env.SVRNG_PAY_KEY;

// 2. Créez une facture
const response = await fetch('https://api.svrngpay.com/v1/invoices', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${SVRNG_PAY_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `order-${orderId}`
  },
  body: JSON.stringify({
    amount: 1500.00,
    currency: 'USD',
    description: 'Mandat — Constitution Delaware C-Corp',
    accepted_chains: ['usdc-eth', 'usdt-eth', 'btc', 'sol'],
    webhook_url: 'https://yoursite.com/webhooks/svrngpay',
    metadata: { order_id: orderId, customer_email: '[email protected]' }
  })
});

const { payment_url, invoice_id, expires_at } = await response.json();

// 3. Redirigez votre client vers le payment_url
// → https://pay.svrngpay.com/inv_a8f3b9c2d1e4f5
RÉPONSE
{
  "id": "inv_a8f3b9c2d1e4f5",
  "object": "invoice",
  "status": "awaiting_payment",
  "amount": 1500.00,
  "currency": "USD",
  "payment_url": "https://pay.svrngpay.com/inv_a8f3b9c2d1e4f5",
  "created_at": "2026-04-29T14:23:11Z",
  "expires_at": "2026-04-29T15:23:11Z",
  "livemode": false
}
Authentification

Bearer token. Test ou live.

Toutes les requêtes API utilisent l'authentification Bearer dans l'en-tête Authorization. Les clés sont préfixées pour rendre évidente la distinction entre test et production.

TEST
sp_test_4F2c7A8d9E...

Faux paiements, test wallets fournis. Aucune transaction onchain réelle. Idéal pour développement et CI.

LIVE
sp_live_7B3a8F4e2D...

Transactions onchain réelles, fonds réels. Uniquement après vérification KYC complète et activation par l'équipe SVRNG Pay.

RESTRICTED
sp_rk_9D4f2A7c1B...

Clés à scope restreint (read-only ou par endpoint). Recommandées pour intégrations tierces, scripts, agents.

Webhooks

Signature HMAC obligatoire. Toujours vérifier.

Tous les webhooks sont signés avec HMAC-SHA256 en utilisant un secret partagé. Si vous ne vérifiez pas la signature, n'importe qui peut forger un webhook qui ressemble au nôtre. Vérifiez. Toujours.

// Express.js — vérification de signature webhook
import crypto from 'crypto';
import express from 'express';

const WEBHOOK_SECRET = process.env.SVRNG_PAY_WEBHOOK_SECRET;

const app = express();

// Important : utilisez le raw body, pas le JSON parsé
app.post('/webhooks/svrngpay',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['svrngpay-signature'];
    const timestamp = req.headers['svrngpay-timestamp'];
    const payload   = req.body.toString();

    // 1. Vérifier que le timestamp est récent (≤ 5 min)
    if (Math.abs(Date.now() / 1000 - timestamp) > 300) {
      return res.status(401).send('timestamp expired');
    }

    // 2. Reconstruire la signature attendue
    const expected = crypto
      .createHmac('sha256', WEBHOOK_SECRET)
      .update(`${timestamp}.${payload}`)
      .digest('hex');

    // 3. Comparaison constante (timing-attack-safe)
    if (!crypto.timingSafeEqual(
        Buffer.from(signature), Buffer.from(expected))) {
      return res.status(401).send('invalid signature');
    }

    // 4. Maintenant seulement, traiter l'événement
    const event = JSON.parse(payload);
    switch (event.type) {
      case 'invoice.confirmed':
        // Le paiement est confirmé onchain au seuil configuré
        fulfillOrder(event.data.invoice_id, event.data.metadata);
        break;
      case 'invoice.expired':
        notifyCustomer(event.data.invoice_id);
        break;
    }

    res.status(200).send('ok');
  }
);
ATTENTION
Si vous accusez réception du webhook (200) avant d'avoir vérifié la signature, vous validez potentiellement des paiements forgés. Vérifiez d'abord, traitez ensuite, répondez 200 à la fin.
Types d'événements

Événements webhook disponibles.

Type Quand
invoice.created Une facture est créée et un payment_url est généré.
invoice.detected Une transaction onchain est détectée à l'adresse de la facture (0 confirmations).
invoice.confirming Confirmations en cours. Émis à chaque nouvelle confirmation pour permettre le suivi.
invoice.confirmed Le paiement atteint le seuil de confirmations. Vous pouvez délivrer le bien ou service.
invoice.underpaid Un montant inférieur à celui demandé est reçu (volatilité du taux pendant la fenêtre de paiement).
invoice.overpaid Un montant supérieur est reçu. Le surplus reste dans le wallet du merchant.
invoice.expired La fenêtre de paiement expire sans paiement détecté (TTL configuré, défaut 60 min).
invoice.refund_initiated Un remboursement est initié manuellement par le merchant depuis le dashboard.
Seuils de confirmation

Sécurité finalité. Par chaîne.

Le seuil de confirmation détermine quand invoice.confirmed est émis. Voici les valeurs par défaut, équilibrées entre sécurité et UX. Configurables vers le haut sur les tiers Pro et Concierge pour les transactions à très haut montant.

Chaîne / actif Défaut Temps approx. Haut montant
USDC sur Ethereum 12 confirmations ~ 3 minutes 64 (institutionnel)
USDT sur Ethereum 12 confirmations ~ 3 minutes 64
Ether (ETH) 12 confirmations ~ 3 minutes 64
Bitcoin (BTC) 3 confirmations ~ 30 minutes 6 (standard banking)
Solana (SOL · USDC-SOL) 32 slots (finalisé) ~ 13 secondes ≥ 64 slots
RÉFÉRENCE
Ces seuils sont alignés avec les pratiques institutionnelles. Cboe Digital et Coinbase utilisent 64 confirmations pour ETH/USDC sur les comptes institutionnels haut volume. 6 confirmations sont le standard historique BTC (~ 60 min). Solana atteint la finalité économique au slot 32 selon la documentation Solana Foundation.
Idempotency

Réessayer sans doubler. Toujours.

Toutes les requêtes POST acceptent un en-tête Idempotency-Key. SVRNG Pay déduplique automatiquement les requêtes ayant la même clé pendant 24 heures. Si votre serveur crash entre la création de facture et la persistance en DB, vous pouvez rejouer la requête sans craindre de créer deux factures.

curl https://api.svrngpay.com/v1/invoices \
  -H "Authorization: Bearer sp_live_..." \
  -H "Idempotency-Key: order-2026-04-29-7842" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1500, "currency": "USD"}'
Erreurs

Codes HTTP standards.

Tous les errors retournent un body JSON structuré avec un type, un code, un message humain, et un request_id à fournir si vous nous écrivez.

{
  "error": {
    "type": "invalid_request",
    "code": "amount_too_low",
    "message": "Le montant minimum est 1.00 USD.",
    "param": "amount",
    "request_id": "req_a8f3b9c2d1"
  }
}
400 · requête invalide
401 · clé invalide
403 · non autorisé
404 · ressource introuvable
429 · rate limit dépassé
5xx · erreur serveur
Rate limits

Limites par environnement.

Test : 100 requêtes/minute par clé. Live Standard : 500 req/min. Live Pro : 2 000 req/min. Live Concierge : 10 000 req/min ou plafond négocié. Headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset sur chaque réponse.

Versioning

Compatible en avant.

Version actuelle : 2026-04-15. Spécifiez SVRNG-Pay-Version: 2026-04-15 pour figer votre intégration. Les changements breaking sortent dans une nouvelle version datée ; l'ancienne reste supportée 12 mois minimum. Vous êtes notifié 90 jours avant toute déprécation.

SDKs officiels

Quatre langages. Plus à venir.

Chaque SDK couvre l'API complète, gère l'authentification, vérifie les signatures de webhook, et expose des types stricts dans les langages typés.

Node.js / TypeScript
npm install @svrngpay/node
Python
pip install svrngpay
PHP
composer require svrngpay/svrngpay-php
Go
go get github.com/svrngpay/svrngpay-go
SDK ROADMAP
Ruby (Q3 2026), Java/Kotlin (Q3 2026), .NET / C# (Q4 2026), Rust (Q1 2027). Demandez votre langage préféré sur notre formulaire — la priorité est ajustée selon la demande merchants.
Prêt à intégrer ?

Une heure. Pas plus.

Créez un compte test, générez votre première facture, vérifiez votre premier webhook. L'intégration complète prend une heure pour un développeur compétent.

Obtenir une clé de test Parler à un développeur SVRNG Pay