API Kryptis Pay

Démarrage en 3 étapes

1. Créez un compte et choisissez un username (Profil → Développeurs & API).
2. Générez une clé API — elle commence par ak_ et n'est affichée qu'une seule fois. Par défaut la clé a les scopes read,write (case « lecture seule » disponible pour restreindre), une expiration optionnelle (date au choix, ou jamais par défaut), et peut être créée en mode bac à sable (préfixe test_ — voir ci-dessous) pour intégrer sans toucher à de vrais fonds. Stockez-la comme un secret (variable d'environnement, jamais dans le code source).
3. Appelez l'API avec l'en-tête Authorization: Bearer ak_....

Base URL, authentification & scopes

Toutes les requêtes se font sur /api/v1. Chaque requête porte votre clé dans l'en-tête Authorization :

Authorization: Bearer ak_xxxxxxxxxxxxxxxxxxxx

• Une clé révoquée ou expirée (depuis « Mes clés API ») répond immédiatement 401. L'expiration se règle à la création de la clé — aucune par défaut.
• Deux modes de clé : ak_... (production, wallet réel) et test_... (bac à sable, wallet fictif isolé — voir Bac à sable).
• last_used_at est mis à jour à chaque appel — surveillez vos clés inactives.
• Limite de débit : 60 requêtes/minute par clé → au-delà 429.
• Scopes : read (consultation) et write (création de lien, retrait, config webhook). Une clé read seule répond 403 sur un appel write.
• Rotation : depuis le tableau de bord (pas via l'API), une clé peut être régénérée sans interruption — l'ancienne est révoquée, une nouvelle est émise avec les mêmes scopes.
• Idempotence : sur les opérations qui déplacent des fonds, ajoutez l'en-tête Idempotency-Key: <uuid> — une requête rejouée avec la même clé ne débite/crédite qu'une fois (24h de mémorisation).

Qui peut payer — et retirer — sans compte complet ?

Ce n'est pas un processeur de paiement carte bancaire ouvert. Un paiement de lien est un transfert wallet-à-wallet fermé — le payeur doit disposer d'un compte Kryptis Pay, ou en obtenir un en quelques secondes :

• Utilisateur existant — se connecte et paie directement, sans plafond spécifique lié à son statut d'invité.
• Invité anonyme — vérifie son email par un code à usage unique (OTP), obtient automatiquement un wallet léger, le finance (Mobile Money ou crypto) puis paie. Aucune inscription classique requise. Plafond 100 USDT glissant sur 30 jours (dépôts + paiements de liens confondus) tant qu'il n'a pas de compte complet + KYC.

Attention à ne pas confondre ce plafond payeur avec celui qui s'applique à votre propre compte (celui qui détient la clé API) quand vous retirez des fonds — les comptes invités ne peuvent pas créer de clé API, mais un compte complet pas encore vérifié KYC le peut, et reste plafonné :

• Plafond 2000 USDT cumulés à vie sur les retraits (POST /withdrawals/crypto et /withdrawals/local), tant que kyc_status de votre compte n'est pas approved — partagé entre les deux canaux (crypto + Mobile Money confondus, pas 2000 chacun). Ce cumul ne se réinitialise jamais.
• Au-delà : 403 avec le solde restant disponible dans le message d'erreur. Seule solution pour continuer à retirer : compléter le KYC du compte (hors périmètre API, depuis le tableau de bord) — au-delà, le plafond ne s'applique plus.
• Ce plafond est distinct du plafond de paiement invité (100 USDT/30j ci-dessus) : l'un limite les fonds entrants sans KYC sur un wallet invité, l'autre les fonds sortants sans KYC sur votre propre compte marchand.

Le parcours payeur se passe entièrement sur le site Kryptis Pay (page /pay/@slug) — vous n'avez rien à implémenter côté payeur, seulement à partager l'URL du lien créé via l'API. Le retrait, lui, est déclenché directement par votre clé API — voir Retraits (payouts).

Premier appel : consulter le solde

curl /api/v1/balance \
  -H "Authorization: Bearer ak_votre_cle"

import requests

r = requests.get(
    "/api/v1/balance",
    headers={"Authorization": "Bearer ak_votre_cle"},
    timeout=10,
)
r.raise_for_status()
print(r.json())   # {'username': 'marc', 'balance_usdt': '42.50', 'kyc_status': 'approved'}

const res = await fetch("/api/v1/balance", {
  headers: { Authorization: "Bearer ak_votre_cle" },
});
if (!res.ok) throw new Error(`API ${res.status}`);
const data = await res.json();
console.log(data);   // { username: 'marc', balance_usdt: '42.50', kyc_status: 'approved' }

$ch = curl_init("/api/v1/balance");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer ak_votre_cle"],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($data);

Conventions & bonnes pratiques

• Réponses en JSON. Les montants sont des chaînes décimales ("25.00") — parsez-les en décimal exact (Decimal, BigNumber), jamais en float.
• Horodatages au format ISO 8601, UTC.
• En cas de 429 ou 5xx : réessayez avec un backoff exponentiel (1s, 2s, 4s…).
• Sur les retraits, envoyez toujours un Idempotency-Key unique par tentative logique — un retry réseau ne doit jamais redéclencher un second envoi de fonds.
• Ne partagez jamais une clé ak_ côté client (app mobile, navigateur) — uniquement serveur à serveur.
• Créez une clé par intégration (boutique, script, partenaire) pour révoquer sans tout casser, et limitez son scope à read si elle n'a pas besoin d'écrire.

Codes d'erreur

Format d'erreur uniforme : {"detail": "message explicatif"}

Webhooks

Une fois votre URL configurée (POST /webhooks/configure), les événements sont envoyés en POST JSON, signés en HMAC-SHA256 dans l'en-tête X-Kryptis-Signature (format sha256=<hex>). Livraison avec retries en backoff exponentiel (jusqu'à 6 tentatives) si votre serveur ne répond pas 2xx.

{
  "event": "payment.completed",
  "data": {
    "link_id": "0f4c9a3e-...",
    "slug": "marc-boutique",
    "label": "Commande #42",
    "amount_coins": "25.00",
    "payer": "jean_dupont",
    "payment_id": "7ad1..."
  }
}

import hmac, hashlib

def verify(body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

• Répondez 2xx rapidement (< 5 s) ; faites le traitement lourd en asynchrone.
• Rendez votre traitement idempotent : le même événement peut être livré plusieurs fois.
• Rejetez toute requête dont la signature ne correspond pas.

Cas d'usage