Authentification (clés API)
Authentifiez vos requêtes à l'API Cardencer avec votre clé secrète dans l'en-tête api-key, et utilisez les clés publiables dans le navigateur.
Cardencer utilise des clés API. Chaque clé appartient à un seul compte marchand et à un seul environnement.
| Clé | Préfixe | Usage | Où elle se trouve |
|---|---|---|---|
| Clé API secrète | snd_ (sandbox), prd_ (production) |
Tous les appels API côté serveur : paiements, remboursements, clients, listes. | Uniquement sur votre serveur. |
| Clé publiable | pk_snd_, pk_prd_ |
Initialiser le SDK de paiement. Elle s'utilise avec le client_secret d'un paiement et ne peut, à elle seule, ni créer de paiements ou de remboursements, ni lister des objets. |
Sans risque sur votre site ou dans votre application. |
| ID de profil | pro_ |
Identifie votre profil d'entreprise auprès du SDK. Ce n'est pas un identifiant d'authentification. | Sans risque sur votre site ou dans votre application. |
Obtenez vos clés#
- Ouvrez le dashboard et rendez-vous dans API keys.
- Créez une clé de test pour la sandbox. Les clés de production deviennent disponibles une fois votre compte vérifié.
- Copiez immédiatement la clé secrète complète. Cardencer stocke les clés sous forme hachée et n'affiche la valeur complète qu'une seule fois. Une valeur comme
prd_9xSUi5pW**********n'est qu'un identifiant masqué et ne permet pas de s'authentifier.
La clé publiable, l'ID de profil et la clé de signature des webhooks figurent sur la même page.
Authentifiez une requête#
Envoyez la clé secrète dans l'en-tête api-key. Utilisez HTTPS : les requêtes en HTTP simple sont refusées.
curl https://sandbox.cardencer.com/payments/pay_mbabizu24mvu3mela5njyhpit4 \
-H "api-key: snd_REPLACE_WITH_YOUR_FULL_KEY"const res = await fetch("https://sandbox.cardencer.com/payments/pay_mbabizu24mvu3mela5njyhpit4", {
headers: { "api-key": process.env.CARDENCER_API_KEY },
});import os, requests
res = requests.get(
"https://sandbox.cardencer.com/payments/pay_mbabizu24mvu3mela5njyhpit4",
headers={"api-key": os.environ["CARDENCER_API_KEY"]},
)Une clé absente, révoquée ou associée au mauvais environnement renvoie :
{
"error": {
"type": "invalid_request",
"message": "API key not provided or invalid API key used",
"code": "IR_01"
}
}Pour corriger l'erreur, vérifiez que le préfixe de la clé correspond à l'hôte (snd_ → sandbox.cardencer.com, prd_ → api.cardencer.com) et que vous avez copié la valeur complète, et non la valeur masquée.
Gardez votre clé secrète… secrète#
- N'insérez jamais de clé
snd_ouprd_dans du JavaScript côté navigateur, dans une application mobile ou dans un dépôt public. Utilisez-y la clé publiable. - Chargez la clé depuis une variable d'environnement ou un gestionnaire de secrets, jamais depuis le code source.
- Conservez une seule copie par environnement et évitez de la dupliquer entre plusieurs systèmes.
- En cas de fuite, créez une nouvelle clé dans API keys, déployez-la, puis supprimez l'ancienne.
Limites de débit et verrouillage#
Si vous envoyez trop de requêtes en peu de temps, Cardencer répond avec un code HTTP 429. Réessayez avec un backoff exponentiel (par exemple 1 s, 2 s, 4 s) et étalez vos traitements par lots dans le temps. Contactez le support si vous avez besoin d'une limite plus élevée.
Un 429 peut aussi signifier qu'un objet est verrouillé parce qu'une autre requête est en train de le modifier (par exemple deux captures simultanées sur le même paiement). Le message indique alors « access to this object is restricted due to ongoing utilization by another API request ». Patientez un instant puis réessayez ; n'envoyez pas d'écritures simultanées sur un même paiement.