Obtenir vos credentials

Avant tout, l'équipe Nex doit créer une intégration pour vous. C'est elle qui détient la console d'admin (CMMS) — vous n'avez pas d'auto-provisioning V1.

1. Demander la création de votre intégration

Envoyez à partners@paywithnex.com :

Nom commercial de votre application (ex: MaishaPay, MyTerminal Pro).
URL HTTPS du webhook où Nex POST les événements (ex: https://api.maishapay.cd/webhooks/nex).
Canal sécurisé pour vous transmettre les secrets (jamais par email plaintext — utilisez un coffre partagé, Signal, ou un autre canal chiffré convenu).
Environnement cible : staging ou production.

Délai de provisioning : généralement 1 jour ouvré.

Pré-requis HTTPS

Nex refuse les webhook URL en http://. Votre endpoint doit être servi en HTTPS avec un certificat valide (Let's Encrypt convient).

2. Récupérer vos credentials

Une fois l'intégration créée, Nex vous transmet 3 valeurs, affichées une seule fois dans la console et ensuite irrécupérables :

Valeur	Format	Utilité
`id` (Integration ID)	UUID v4	Identifie votre intégration côté Nex. Pas secret, peut être loggé.
`api_key`	`nex_sk_live_xxxxxxxxxxxxxxxxxxxxxxxx` (~40 chars)	Secret. Utilisé en header `Authorization: Bearer ...` sur l'API publique.
`webhook_secret`	`nex_whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxx` (~40 chars)	Secret. Utilisé pour vérifier la signature HMAC des webhooks entrants.

Stockez ces valeurs dans un secret manager (AWS Secrets Manager, Doppler, HashiCorp Vault, etc.). Ne les commitez jamais dans un repo Git — même un repo privé.

Multi-clés

Vous pouvez demander à Nex de créer plusieurs api_key actives en parallèle. C'est utile pour rouler une nouvelle clé sur un sous-ensemble de terminaux sans casser le reste de la flotte. Voir Cycle de vie.

3. Tester l'authentification

Le plus rapide pour valider que vos credentials fonctionnent : essayer une demande de connexion sur un téléphone qui n'existe pas. Vous devez recevoir une réponse 200 (Nex renvoie une réponse factice pour éviter d'énumérer les marchands).

bash

curl -sw "\nHTTP %{http_code}\n" \
  -X POST "https://dev.paywithnex.com/api/partners-public/connections/request" \
  -H "Authorization: Bearer nex_sk_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantPhone": "+237600000000",
    "scopes": ["orders.write"],
    "requestedReason": "Smoke test auth"
  }'

Réponses attendues

Cas	Code	Body
✅ Auth OK	`200`	`{"connectionId":"<uuid>","status":"pending","expiresAt":"..."}`
❌ Bearer manquant	`401`	`{"code":"INVALID_INTEGRATION_CREDENTIALS"}`
❌ Bearer erroné	`401`	`{"code":"INVALID_INTEGRATION_CREDENTIALS"}`
❌ Intégration révoquée	`401`	`{"code":"INTEGRATION_REVOKED"}`

Si vous recevez 401, vérifiez : le préfixe Bearer dans le header, la copie complète de la clé (pas de troncature au copier-coller), l'environnement (staging vs production).

4. Configurer votre receiver webhook

Avant d'aller plus loin, votre endpoint webhook doit être prêt à recevoir des POST signés. Voir Recevoir les webhooks pour le format général et Guide implémentation receiver pour le code (Express et Fastify).

Étapes suivantes

Une fois vos credentials testés :

Obtenir vos credentials ​

1. Demander la création de votre intégration ​

2. Récupérer vos credentials ​

3. Tester l'authentification ​

4. Configurer votre receiver webhook ​