Backend

Intégrer NaabigaPay en REST / cURL

L'API brute : créer un lien, lire un statut, vérifier une signature de webhook. Transposable dans tout langage.

À lire en premier. Ces appels portent la clé secrète (sk_live_…) : exécutez-les depuis votre serveur, jamais depuis un navigateur ou une app, où la clé serait extractible. Auth par Authorization: Bearer sk_… ; l'en-tête X-Api-Key: sk_… est aussi accepté.

1.Créer un lien de paiement

POST/v1/payment-links. Ajoutez un Idempotency-Key unique par tentative pour éviter tout double lien en cas de retry réseau.

cURL · créer un lien

curl -X POST https://api.pay.naabiga.com/api/v1/payment-links \
  -H "Authorization: Bearer sk_live_<keyId>.<secret>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cmd-1042" \
  -d '{
    "amount": 5000,
    "reference": "CMD-1042",
    "description": "Commande CMD-1042",
    "return_url": "https://monsite.com/merci",
    "cancel_url": "https://monsite.com/panier",
    "single_use": true
  }'

Réponse 201 : le champ url est la page où le client paie. Pour un montant libre, remplacez amount par amount_min, amount_max et une description.

201 Created

{
  "token": "9f3c8b1e...",
  "url": "https://pay.naabiga.com/link/9f3c8b1e...",
  "amount": 5000,
  "currency": "XOF",
  "reference": "CMD-1042",
  "status": "pending"
}

2.Lire le statut d'un paiement

GET/v1/payments/{reference} renvoie le statut : pending, success, failed ou cancelled.

cURL · statut d'un paiement

curl https://api.pay.naabiga.com/api/v1/payments/CMD-1042 \
  -H "Authorization: Bearer sk_live_<keyId>.<secret>"

# -> {
#      "reference": "CMD-1042",
#      "type": "payment",
#      "amount": 5000,
#      "currency": "XOF",
#      "status": "success"
#    }

3.Vérifier un webhook

NaabigaPay envoie POST à l'URL enregistrée dans le portail marchand, avec X-NPay-Event: payment.succeeded et X-NPay-Signature = HMAC-SHA256 du corps brut, clé = secret du webhook. Recalculez la signature sur le corps brut reçu et comparez-la (temps constant) avant de créditer.

Shell · recalculer la signature

# En-têtes reçus :
#   X-NPay-Event: payment.succeeded
#   X-NPay-Signature: <HMAC-SHA256 du corps BRUT, clé = secret du webhook>

# Recalculez sur le corps brut exact reçu ($RAW_BODY) :
printf '%s' "$RAW_BODY" \
  | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -hex \
  | sed 's/^.* //'

# La sortie doit être égale à l'en-tête X-NPay-Signature (comparaison à temps
# constant). N'acceptez le paiement, et ne créditez selon VOTRE montant stocké,
# que si les deux correspondent.

Astuce. Signez et vérifiez toujours sur le corps brut : un JSON re-sérialisé (espaces, ordre des clés) change les octets et invalide la signature.

Référence rapide

Méthode	Endpoint	Rôle
POST	`/v1/payment-links`	Créer un lien de paiement
GET	`/v1/payments/{reference}`	Statut d'un paiement

Base : https://api.pay.naabiga.com/api/v1 · Auth : Authorization: Bearer sk_…. Voir la documentation complète et le format des webhooks.