Nex Docs

Appearance

StableAudienceDevMétierOwner@partners-teamDernière revue2026-05-24

Connecter un marchand ​

Avant de pouvoir encaisser pour un marchand, vous devez obtenir son consentement explicite. Nex ne crée jamais de lien silencieux entre une intégration et un marchand. Cette procédure couvre les 5 étapes du flow standard.

Vue d'ensemble ​

Procédure pas-à-pas ​

Étape 1 — Faire la demande de connexion ​

Vous appelez l'API publique en passant le téléphone E.164 du représentant légal du marchand (celui qui a fait le KYC chez Nex).

bash
curl -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": "+242069887766",
    "scopes": ["orders.write"],
    "requestedReason": "Terminal MaishaPay déployé chez la boulangerie"
  }'
ChampTypeDescription
merchantPhonestringE.164 obligatoire (+<country><number>), pas d'espaces. CEMAC : +237, +242, +241, +240, +235, +236.
scopesstring[]Au moins un scope. V1 : orders.write (créer des commandes), orders.read (lire le statut).
requestedReasonstringOptionnel mais fortement recommandé : affiché au marchand dans l'email et sur le dashboard. Sans lui, le marchand peut refuser pensant à du spam.

Réponse 200 :

json
{
  "connectionId": "0f165ba2-ec79-4b1a-b5e3-072e6a44a229",
  "status": "pending",
  "expiresAt": "2026-05-30T16:44:07.768Z",
  "alreadyExisted": false
}

Anti-énumération

Si le téléphone est inconnu de Nex, vous recevez quand même un connectionId (UUID factice). C'est volontaire : Nex ne révèle pas quels marchands sont enregistrés. Un GET /connections/<factice> renverra 404 plus tard.

Vous ne pouvez donc pas distinguer un succès réel d'un téléphone inconnu côté API. Avant de produire massivement des demandes, vérifiez par un autre canal que le marchand a bien un compte Nex.

Étape 2 — Le marchand reçoit un email ​

Nex envoie automatiquement un email au représentant légal du marchand. Le message contient :

  • Votre nom d'intégration (MaishaPay par exemple)
  • Le requestedReason que vous avez fourni
  • Les scopes demandés en clair (Créer des commandes (QR de paiement) en votre nom)
  • Un bouton Voir la demande qui pointe vers https://business.paywithnex.com/merchant/integrations

Pas de magic-link à signer — l'authentification se fait par login normal sur le business-dashboard (compte marchand existant).

Étape 3 — Le marchand arbitre depuis son portail ​

Sur /merchant/integrations, le marchand voit votre demande en attente avec deux boutons :

  • Autoriser → la connexion passe à active. Vous pouvez encaisser immédiatement.
  • Refuser → la connexion passe à rejected. Vous devez recréer une demande (avec un meilleur motif, après contact avec le marchand).

Si le marchand ne fait rien dans les 7 jours suivant la création (pendingExpiresAt), la connexion passe à expired automatiquement.

Étape 4 — Savoir que la connexion est active ​

V1, vous n'avez pas de webhook connection.activated (prévu pour spec ultérieure). Trois options :

  1. Polling périodique (recommandé) — toutes les 5-10 min sur les connexions pending que vous attendez :

    bash
    curl -X GET "https://dev.paywithnex.com/api/partners-public/connections/0f165ba2-..." \
  -H "Authorization: Bearer nex_sk_live_VOTRE_CLE"

    Renvoie :

    json
    {
  "id": "0f165ba2-...",
  "merchantId": "0d85d7a4-...",
  "status": "active",
  "scopes": ["orders.write"],
  "activatedAt": "2026-05-24T08:15:23.000Z"
}

  2. Confirmation hors-bande — le marchand vous appelle ou vous envoie un email après acceptation. Plus simple en V1 si vous avez peu de connexions à provisionner.

  3. Tentative naïve — vous essayez de créer une commande (POST /orders). Si vous recevez 403 NO_ACTIVE_CONNECTION, le marchand n'a pas encore arbitré. Coût d'un appel API en plus, mais pas de polling à coder.

Étape 5 — Stocker le merchantId côté votre app ​

Une fois la connexion active, vous récupérez le merchantId dans la réponse GET /connections/.... Conservez-le : c'est ce que vous passez en paramètre merchantId à chaque création de commande (voir Encaisser pour un marchand).

Ce merchantId est aussi l'identifiant que vous loggez côté votre application pour tracer qui paie pour qui.

Cas particuliers ​

Le marchand a déjà une connexion active avec vous ​

Si vous re-demandez une connexion pour un marchand déjà connecté, l'API renvoie la connexion existante avec alreadyExisted: true. Idempotence : 2 POST /connections/request consécutifs sur le même couple = 1 seule connexion en BD. Pas d'erreur, pas de doublon.

json
{
  "connectionId": "0f165ba2-...",
  "status": "active",
  "alreadyExisted": true
}

Le marchand a refusé ​

Vous ne pouvez pas re-demander immédiatement — vous obtenez l'ancienne connexion rejected (alreadyExisted: true). Discutez avec le marchand, comprenez pourquoi, puis demandez à Nex de purger la rejected pour que vous puissiez recréer une demande (procédure manuelle V1).

Vous avez changé d'avis avant le consentement ​

Pas d'endpoint pour annuler une demande pending côté partner V1. Soit vous attendez les 7 jours d'expiration, soit vous demandez à Nex (CMMS) de la passer à revoked manuellement.

Voir aussi ​

Nex — Plateforme fintech CEMAC