Authentification

Deux types de clés, deux pouvoirs très différents. Les confondre est la faute la plus coûteuse d'une intégration.

Deux types de clés

Chaque compte dispose de deux clés par environnement. Elles n'ouvrent pas les mêmes portes, et les confondre est la faute la plus coûteuse d'une intégration.

Envoyer la clé

Toujours en en-tête Authorization, jamais en paramètre d'URL — une clé dans une URL se retrouve dans les logs d'accès, l'historique du navigateur et le Referer envoyé aux sites tiers.

Authorization: Bearer sk_live_VOTRE_CLE_SECRETE
Content-Type: application/json

Sandbox et production

Le mode est porté par la clé elle-même. Un serveur de recette qui détient une clé sk_sandbox_ ne peut pas encaisser en vrai, même s'il vise par erreur l'URL de production.

Déclarer le domaine d'une clé publique

Le résultat d'un paiement ouvert dans le navigateur vous est rendu par postMessage. Pour qu'aucune page tierce ne puisse l'intercepter en encadrant le checkout, NguePay n'émet que vers l'origine déclarée sur la clé publique, jamais vers '*'.

Une clé publique sans domaine déclaré est refusée avec NGP015. Renseignez-le dans votre dashboard, onglet Clés API, au format https://votre-boutique.ci — schéma et hôte, sans chemin.

Le même domaine borne l'URL de retour. Une session créée avec la clé publique n'accepte un return_url — ou un metadata.return_url — que s'il a la même origine que le domaine déclaré : même schéma, même hôte, même port. Sinon, l'appel est refusé en 422 (NGP_VALIDATION, détail sur le champ fautif). Sans cette règle, n'importe qui pourrait ouvrir une page de paiement à votre nom dont le bouton « Retour » mènerait ailleurs.

Mot de passe oublié

Deux endpoints publics, sans authentification. Ils concernent le compte dashboard d'un marchand, jamais ses clés API — une clé perdue se révoque et se remplace, elle ne se réinitialise pas.

curl -X POST https://api.live.nguepay.com/api/v1/auth/password/forgot \
  -H "Content-Type: application/json" \
  -d '{"email": "marchand@boutique.ci"}'

curl -X POST https://api.live.nguepay.com/api/v1/auth/password/reset \
  -H "Content-Type: application/json" \
  -d '{
    "token": "le-jeton-recu-par-email",
    "email": "marchand@boutique.ci",
    "password": "NouveauMotDePasse2026",
    "password_confirmation": "NouveauMotDePasse2026"
  }'

Ce dernier point compte : une réinitialisation fait souvent suite à une compromission. Laisser vivre les jetons existants laisserait l'intrus en place.

Un lien expiré, déjà utilisé ou visant un autre compte répond NGP019.

Compte dashboard : mot de passe et session

Le compte dashboard est celui d'une personne ; les clés API sont celles d'un serveur. Les règles ci-dessous ne concernent que le premier.

Certaines actions ne sont permises qu'avec une session dashboard, jamais avec une clé API. C'est le cas des coordonnées de notification (notification_email, notification_phone) : les modifier avec une clé répond 403 avec NGP023. Une clé secrète volée ne doit pas permettre de détourner les alertes du compte.

Double authentification

La double authentification ajoute à la connexion un code à 6 chiffres produit par une application d'authentification (TOTP : Google Authenticator, Authy, 1Password…). Elle est facultative pour un compte marchand, et fortement recommandée dès que le compte encaisse en production.

L'activer

1. Dans le dashboard, Paramètres › Sécurité › Double authentification, saisissez votre mot de passe actuel.
2. Scannez le QR code avec votre application, ou saisissez la clé affichée.
3. Confirmez avec le premier code à 6 chiffres.
4. Notez les 8 codes de secours : ils ne seront plus jamais affichés.

À l'activation, toutes vos autres sessions ouvertes sont fermées : elles avaient été obtenues sans second facteur. Votre profil (GET /v1/auth/me) expose alors two_factor_enabled: true.

Ce que ça change à la connexion

Avec la double authentification active, un mot de passe correct ne suffit plus : POST /v1/auth/login ne délivre aucun jeton et renvoie un défi.

{
  "success": true,
  "data": { "two_factor_required": true, "challenge": "3b9f…" },
  "message": "Saisissez le code de votre application d'authentification."
}

curl -X POST https://api.live.nguepay.com/api/v1/auth/two-factor/challenge \
  -H "Content-Type: application/json" \
  -d '{"challenge": "3b9f…", "code": "482913"}'

À la place de code, vous pouvez envoyer recovery_code avec un de vos codes de secours. Chaque code de secours ne sert qu'une fois.

Par API

Le dashboard fait ces appels pour vous ; ils sont documentés pour qui pilote son compte autrement. Tous exigent une session dashboard.

Un mot de passe actuel absent ou faux, ou un code refusé, répond 422 avec NGP022.

Vérifier que tout est branché

curl https://api.sandbox.nguepay.com/api/v1/ping \
  -H "Authorization: Bearer sk_sandbox_VOTRE_CLE"

{
  "success": true,
  "data": { "merchant": "3f8c…", "mode": "sandbox" },
  "message": "pong"
}

Limites de débit

Au-delà de votre quota, l'API répond 429 avec NGP007 et un en-tête Retry-After. Attendez le délai indiqué plutôt que de réessayer en boucle : les tentatives refusées comptent aussi.

Règles d'hygiène

• Une clé par environnement, et une par service qui appelle réellement l'API
• Jamais de clé dans un dépôt Git, un bundle front, une capture d'écran ou un ticket
• Révoquer immédiatement une clé dont on doute — la révocation est instantanée
• Masquer les clés dans vos logs : sk_live_****a1b2