Documentation — Setlix

01

Démarrage rapide

Trois étapes pour encaisser un premier paiement :

Connectez votre compte Stripe depuis le dashboard Setlix.
Récupérez votre clé API sk_live_… dans Paramètres → API.
Appelez POST /v1/checkout/sessions avec le montant et l'URL de retour.

Exemple minimal en cURL :

              quickstart.sh · cURL · 7 lignes
              POST /v1/checkout/sessions
            

# Créer une session de checkout
curl https://api.setlix.app/v1/checkout/sessions \
  -u sk_live_xxx: \
  -d "amount=4990" \
  -d "currency=eur" \
  -d "success_url=https://votremarque.fr/merci" \
  -d "cancel_url=https://votremarque.fr/panier"

02

Authentification

L'API utilise des clés Bearer transmises en HTTP Basic, comme Stripe. Une clé en mode test (sk_test_…) et une clé en mode live (sk_live_…) par compte. La clé publique (pk_…) est utilisée côté front pour le checkout hébergé.

              auth · header · HTTP Basic
              Authorization
            

Authorization: Basic $(echo -n "sk_live_xxx:" | base64)

03

Créer une session de checkout

La méthode recommandée est la session hébergée. Setlix construit l'URL, gère les méthodes de paiement actives, et redirige vers success_url ou cancel_url.

              checkout.json · request body · 14 lignes
              POST /v1/checkout/sessions
            

POST /v1/checkout/sessions

{
  "amount": 4990,
  "currency": "eur",
  "line_items": [
    { "name": "Veste lin · Sable", "qty": 1, "unit_amount": 3900 },
    { "name": "Livraison standard", "qty": 1, "unit_amount": 490 }
  ],
  "customer_email": "camille@exemple.fr",
  "locale": "fr",
  "success_url": "https://votremarque.fr/merci?session={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://votremarque.fr/panier"
}

04

Webhooks signés HMAC

Setlix envoie des webhooks sur votre endpoint à chaque changement d'état d'une session (session.completed, session.failed, session.expired). Chaque requête porte un en-tête Setlix-Signature signé en HMAC-SHA256 avec un secret partagé.

              verify.ts · Node 20+ · 6 lignes
              HMAC-SHA256
            

// Node 20+
import { createHmac } from 'node:crypto';

const raw = await req.text();
const sig = req.headers.get('Setlix-Signature');
const expected = createHmac('sha256', process.env.SETLIX_WEBHOOK_SECRET).update(raw).digest('hex');
if (sig !== expected) return new Response('invalid', { status: 400 });

05

SDK Node & Python

Deux SDK officiels, typés, idempotents, avec retry exponentiel intégré.

setlix-node

npm install setlix · Compatible avec Node 18+ et Bun.

setlix-python

pip install setlix · Compatible avec Python 3.10+.

              example.ts · setlix-node · 5 lignes
              checkout.sessions.create
            

import Setlix from 'setlix';
const setlix = new Setlix(process.env.SETLIX_KEY);
const session = await setlix.checkout.sessions.create({
  amount: 4990, currency: 'eur', success_url: '/merci', cancel_url: '/panier'
});

06

Migration depuis Stripe

Setlix se branche sur votre compte Stripe existant via Stripe Connect. Vos clients, abonnements, et historique de paiement restent dans Stripe. Setlix ajoute une couche checkout et un dashboard ; il ne déplace aucune donnée régulée.

Connecter Stripe (OAuth Connect) — 3 minutes.
Mapper vos produits Stripe existants — automatique.
Mettre à jour vos endpoints front pour pointer vers Setlix — 15 minutes.

07

Référence API

Endpoints stables de la v1. Base URL : https://api.setlix.app. Toutes les réponses sont en JSON.

// 9 endpoints

Méthode	Chemin	Description
POST	/v1/checkout/sessions	Créer une session de checkout hébergée. Renvoie l'URL de redirection.
GET	/v1/checkout/sessions/{id}	Récupérer l'état d'une session : statut, line items, méthode utilisée.
POST	/v1/payments	Créer un paiement direct hors session (API-first, sans page hébergée).
GET	/v1/payments/{id}	Récupérer un paiement par son identifiant.
POST	/v1/refunds	Émettre un remboursement total ou partiel sur un paiement réussi.
GET	/v1/webhooks/events	Lister les événements webhooks émis sur les 30 derniers jours.
POST	/v1/webhooks/endpoints	Enregistrer un nouvel endpoint webhook avec son secret de signature.
GET	/v1/customers	Lister les clients synchronisés depuis votre compte Stripe.
GET	/v1/balance	Solde disponible, en attente, et payouts à venir, par devise.

08

Erreurs & limites

L'API renvoie des erreurs JSON structurées avec un code stable. Limite par défaut : 100 requêtes/seconde par clé, augmentable sur la formule Atelier.

              error.json · réponse 422 · 8 lignes
              validation_error
            

{
  "error": {
    "type": "validation_error",
    "code": "amount_too_small",
    "message": "Le montant minimum est de 50 centimes.",
    "param": "amount"
  }
}

09

Mode test

Toute clé sk_test_… bascule en mode test. Aucun argent ne transite. Stripe Test Mode est utilisé en sous-jacent. Numéros de carte de test : 4242 4242 4242 4242 (succès), 4000 0000 0000 0002 (échec 3DS), 4000 0027 6000 3184 (3DS requise).

Une question, un cas non couvert, un retour ? Écrivez à contact@setlix.app.

Documentation claire.