Démarrage rapide

En quelques minutes : créez un compte, générez une clé API, rechargez votre solde et vérifiez-le avec une première requête.

Prérequis

  • Un navigateur pour créer votre compte sur le dashboard, ou curl pour tout faire en ligne de commande.
  • Pour les exemples SDK : Python 3.10+ (paquet paylet) ou Node.js 18+ (paquet paylet).
  • Une carte bancaire pour recharger le solde via Stripe (montant compris entre 1 € et 5 000 €).

1. Créer un compte

Deux options : via le dashboard Paylet (formulaire ou connexion avec Google), ou via l'API.

curlPOST /v1/auth/register
curl -X POST https://api.paylet.fr/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "vous@exemple.com",
    "password": "MotDePasseFort123!",
    "password_confirm": "MotDePasseFort123!",
    "first_name": "Camille",
    "last_name": "Dupont",
    "company_name": "Mon Studio"
  }'

La réponse 201 contient votre profil public et un access_token (JWT) utilisable immédiatement pour les appels « dashboard ». Vous pouvez aussi vous connecter avec Google via GET /v1/auth/google.

Pour obtenir un nouveau jeton ensuite, utilisez la connexion :

curlPOST /v1/auth/login
curl -X POST https://api.paylet.fr/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "vous@exemple.com", "password": "MotDePasseFort123!"}'

Réponse 200 : {"access_token": "<jwt>", "token_type": "bearer", "expires_in": 86400}. Le jeton expire après 24 h.

2. Générer une clé API

La clé API sert aux échanges Machine-to-Machine : elle est envoyée dans le header X-API-Key. Elle est distincte du JWT (réservé au dashboard).

curlPOST /v1/api-keys
curl -X POST https://api.paylet.fr/v1/api-keys \
  -H "Authorization: Bearer $PAYLET_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod",
    "scopes": ["read:balance", "write:payment", "read:transactions"]
  }'

La réponse 201 contient la clé complète dans le champ secret (format ak_live_<votre-cle>). Elle n'est affichée qu'une seule fois : conservez-la précieusement. Seul son empreinte (hash SHA-256) est stockée côté Paylet.

Les scopes par défaut sont read:balance, write:payment et read:transactions.

3. Recharger son solde (Stripe)

Le solde est prépayé. Créez une session de rechargement Stripe, puis suivez le lien de paiement renvoyé.

curlPOST /v1/topups
curl -X POST https://api.paylet.fr/v1/topups \
  -H "Authorization: Bearer $PAYLET_JWT" \
  -H "Idempotency-Key: 5f2c1a7e-9b3d-4c6e-8a1f-2b7d9e0c4a13" \
  -H "Content-Type: application/json" \
  -d '{"amount_eur": "10.00"}'

Réponse 201 : {"topup_id": "<uuid>", "checkout_url": "https://checkout.stripe.com/cs_test_<id>", "amount_eur": "10.00", "status": "pending"}. Ouvrez checkout_url dans un navigateur pour régler par carte. Une fois le paiement confirmé, Paylet crédite votre compte (événement webhook topup.completed).

Idempotency-Key obligatoire

Le header Idempotency-Key (un UUID v4) est requis sur POST /v1/topups. Rejouer la même clé renvoie la même session, jamais un double débit.

4. Premières requêtes : vérifier le solde

Le solde est exposé au micro-crédit près. La clé M2M suffit (scope read:balance).

curl https://api.paylet.fr/v1/balance \
  -H "X-API-Key: ak_live_<votre-cle>"

Résultat attendu (structure JSON de la gateway) :

jsonGET /v1/balance — réponse 200
{
  "currency": "EUR",
  "balance_minor": 420000,
  "balance_eur": "0.42",
  "reserved_minor": 0,
  "available_minor": 420000
}

balance_minor est le solde courant en micro-crédits, reserved_minor la part réservée aux paiements en cours, et available_minor ce que vous pouvez réellement dépenser.

Erreurs courantes

codeHTTPCause fréquente
authentication_required401JWT absent ou expiré (il expire après 24 h).
invalid_api_key401Clé M2M inexistante ou révoquée.
invalid_request400Montant de top-up hors de la plage 1 € – 5 000 €.
idempotency_conflict409Même Idempotency-Key réutilisée avec un corps différent.

Et ensuite ?