Plusieurs boutiques

Créez une clé API par site et rattachez-la à sa boutique au moment de la création, dans Développeur, Clés API. Installez ensuite chaque clé sur le site correspondant.

Il n'y a alors rien à transmettre dans l'appel. Une clé installée sur un site EST ce site : Mobupay rattache l'encaissement à sa boutique sans que vous ayez à écrire une ligne. C'est aussi la seule façon qui reste juste si quelqu'un modifie les réglages du module plus tard, ou si votre code de création de paiement est partagé entre plusieurs sites.

Pour savoir ce que porte une clé avant d'intégrer, appelez GET /api/v1/whoami : la réponse rend la boutique rattachée, ou null si la clé dessert tout le compte.

Quand une seule clé dessert plusieurs boutiques (un outil de gestion unique qui encaisse pour deux enseignes, par exemple), nommez la boutique à chaque création de paiement avec storeId. Le champ accepte l'identifiant de la boutique (sto_…) ou son code, celui que vos propres systèmes connaissent déjà.

Il est accepté sur les trois entrées de paiement : POST /payments/sessions, POST /payments/links et POST /payments/direct.

POST https://api.mobupay.nc/api/v1/payments/sessions
Authorization: Bearer sk_live_VOTRE_CLE
Content-Type: application/json

{
  "storeId": "PAITA",                 <-- premier niveau, code ou sto_...
  "order": { "reference": "CMD-1042", "amount": 5000, "currency": "XPF" },
  "redirectUrl":     "https://votre-site.nc/merci",
  "notificationUrl": "https://votre-site.nc/webhook"
}

Si votre clé porte déjà une boutique, elle fait autorité : le corps peut la répéter, jamais la contredire. Nommer une autre boutique est refusé (STORE_KEY_MISMATCH).

Un storeId que Mobupay ne reconnaît pas fait échouer l'appel en 400. Rien n'est encaissé et rien n'est rattaché par défaut. C'est délibéré : un rapprochement faux se découvre des mois plus tard, à la clôture, alors qu'une erreur se voit une fois, en développement, et se corrige.

En retour, la boutique retenue vous est restituée : ce qui entre ressort. Les trois réponses de création portent un objet store de la forme { id, code, name }, les webhooks payment.* et refund.* le portent aussi, et GET /payments/{id} le rend sur tout paiement. Le code y figure, pas seulement l'identifiant : c'est lui que vos systèmes reconnaissent. Sur un rejeu d'idempotence d'un lien de paiement, le champ est absent plutôt que null : rendre null affirmerait qu'il n'y a pas de boutique, alors que le lien existait déjà.

Renommer une boutique ne change pas ce que votre client lit sur son relevé. Ce libellé vient de la plaque commerciale portée par le contrat d'encaissement, pas du nom que vous donnez à la boutique. Deux boutiques qui partagent le même contrat produisent donc le même libellé.

Pour qu'une enseigne apparaisse sous son propre nom au relevé, il lui faut son propre contrat d'encaissement, que vous rattachez ensuite à sa boutique. Parlez-en au support : c'est une démarche contractuelle, pas un réglage.

Avec une clé sk_test_*, un seul contrat existe : celui de l'environnement de test. Le contrat rattaché à votre boutique n'est donc pas employé, et vous ne pouvez pas vérifier en test la ventilation qu'il produira en production.

Mobupay vous le dit plutôt que de vous laisser croire à une recette réussie : la réponse porte alors storeContractIgnored: true. Le rattachement à la boutique, lui, fonctionne normalement, et store vous est bien restitué. Le champ est absent en production.

{
  "paymentId": "pay_2NjK8mLk0093xY",
  "sessionId": "ses_BHl4xKp8mNz12Q",
  "checkoutUrl": "https://checkout.mobupay.nc/session/ses_BHl4xKp8mNz12Q",
  "store": { "id": "sto_7Kq2mZp4nT8xB1", "code": "PAITA", "name": "Boutique de Païta" },
  "storeContractIgnored": true
}

Usage avancé. Le champ merchantConfigId reste accepté sur les trois entrées de paiement : il désigne directement un contrat d'encaissement, sans boutique. Il s'adresse à l'intégrateur qui pilote ses contrats lui-même. La voie normale reste la boutique, qui désigne son contrat sans que vous ayez à le connaître.

Les deux ne se contredisent jamais en silence : si l'appel nomme un contrat et que la boutique en porte un autre, l'appel est refusé (STORE_CONTRACT_CONFLICT). Un arbitrage silencieux changerait la plaque du relevé et la ventilation des fonds sans que vous puissiez le savoir.