Créer une session de paiement

Boutique à laquelle rattacher cet encaissement. Accepte l'identifiant (`sto_*`) **ou le code** de la boutique, celui que vos propres systèmes connaissent déjà. **Champ de premier niveau** : à côté de `externalId`, jamais à l'intérieur de `order`. Une clé inconnue placée dans `order` est écartée en silence, et le paiement partirait alors sur le contrat par défaut sans qu'aucune erreur ne vous prévienne. Facultatif. Si votre clé API est déjà rattachée à une boutique, elle fait autorité et vous n'avez rien à transmettre : le corps peut la répéter, jamais la contredire (`STORE_KEY_MISMATCH`). Une boutique inconnue (`UNKNOWN_STORE`), désactivée (`STORE_INACTIVE`) ou déclarée point de vente physique (`STORE_KIND_MISMATCH`) fait échouer l'appel : elle n'est jamais ignorée. Vos boutiques se créent depuis votre espace marchand, Paramètres puis « Mes offres ». Voir le guide « Plusieurs boutiques » (/docs/guides/boutiques).

**Usage avancé.** Contrat d'encaissement à employer (`mcf_*`), désigné directement. Ce champ reste accepté, mais la voie normale est la boutique : `storeId`, ou une clé API rattachée à une boutique, désigne le contrat sans que vous ayez à le nommer. Facultatif : absent, le contrat actif par défaut s'applique. Si l'appel et la boutique désignent deux contrats différents, l'appel est refusé (`STORE_CONTRACT_CONFLICT`) : Mobupay n'arbitre jamais en silence entre deux contrats, puisque le choix décide du libellé porté au relevé du client et de la ventilation des fonds.

Détail de la commande à payer. Voir sous-objets `items`, `taxDetail`, `platformConfig`, `delivery`.

AUTO (défaut) = capture immédiate après autorisation. MANUAL = autorisation seule, capture différée via `POST /payments/{id}/capture`. En mode MANUAL, l'autorisation a une durée de validité limitée (moins de 7 jours côté réseau carte) : sans capture dans ce délai, elle expire et le client n'est jamais débité. Si un encaissement survenait malgré l'absence de capture, Mobupay émet quand même `payment.captured`.

Identifiant du client à associer (`cus_*`). Triple identification : `customerId` OU `email` OU `externalId`. **Ce champ conditionne l'affichage des cartes déjà enregistrées.** La page de paiement ne propose le portefeuille du client (paiement en un clic) que si la session porte un `customerId` au moment où elle est créée. Sans lui, le client voit un formulaire de saisie vierge, même s'il a déjà enregistré une carte chez vous : la fiche client créée après coup par `saveCustomer` arrive trop tard pour cette page, elle ne sert qu'aux commandes suivantes. Conservez donc le `customerId` reçu dans le webhook `payment.authorized` et renvoyez-le à chaque nouvelle session. Voir le guide « Cartes enregistrées » (/docs/guides/saved-cards). Ne transmettez un `customerId` que pour un utilisateur authentifié chez vous : il donne accès aux cartes du titulaire et permet de payer avec.

Identifie le customer par email (unique par marchand). Sert aussi de pré-remplissage du champ email sur la page de paiement si `saveCustomer=true`. **Obligatoire** pour les sessions anonymes (Option A) : sinon la page demande l'email avant paiement (Option B). Stocké dans `payment.privateData.customerEmail` pour l'envoi du ticket.

Identifie le customer par son ID externe (unique par marchand). Max 255 chars.

Si `true` et aucun customer identifié, crée automatiquement un customer (+ mxWallet) après paiement réussi. Le `customerId` créé est retourné dans le webhook `payment.authorized` (champs `customerId` + `customerCreated`). Ignoré si un customer est déjà identifié. Défaut `false`. **La création a lieu à la fin du paiement, pas à l'ouverture de la page.** Ce champ ne fait donc jamais apparaître le portefeuille sur la session en cours : il sert à obtenir un `customerId` que vous stockez, pour le transmettre aux commandes suivantes. Un intégrateur qui s'appuie sur `saveCustomer` seul, commande après commande, enregistre des cartes que son client ne verra jamais.

Si `true`, la page de paiement affiche une case "Enregistrer ma carte". Requiert un customer identifié OU `saveCustomer=true` (sinon erreur 400). Défaut `false`. À garder à `true` même pour un client qui a déjà des cartes : c'est ce qui lui permet d'en enregistrer une nouvelle.

Le montant `order.amount` inclut les taxes (TTC). Défaut `true`. Si `false`, les taxes sont ajoutées par-dessus.

Code langue de la page de paiement (`fr`, `en`...). 2-5 chars. Défaut `fr`.

URL de redirection après paiement (succès ou échec). Le `paymentId` est passé en query string.

URL de retour dédiée en cas de refus. Par défaut, `redirectUrl` est utilisée. Le client y revient avec `?status=failed&paymentId=…&reference=…` (le code de refus n'est jamais dans l'URL : il est fourni par le webhook `payment.failed` et `GET /payments/{id}`).

Comportement après un refus. `show` (défaut) : la page d'échec Mobupay est affichée (motif du refus, « Réessayer », « Utiliser un autre moyen de paiement », lien de retour vers votre boutique). `redirect` : le client est redirigé immédiatement vers `failureRedirectUrl` (à défaut `redirectUrl`) sans voir la page Mobupay, à vous de gérer l'écran d'erreur. Repli automatique sur `show` si aucune URL de retour valide n'est fournie. Une session expirée n'est pas un refus : le client voit toujours la page « session inactive ».

Comportement après un paiement réussi. `auto` (défaut) : le client est redirigé vers `redirectUrl` si son email est connu (il reçoit son reçu par email), sinon la page de succès Mobupay s'affiche pour qu'il télécharge son reçu. `show` : la page de succès est toujours affichée. `redirect` : redirection systématique vers `redirectUrl`, même sans email.

URL HTTPS de votre webhook : Mobupay y envoie (POST signé) les events du paiement (`payment.authorized`, `payment.captured`, `payment.failed`, etc.). Livrée en complément des endpoints webhook enregistrés.

Données privées libres (JSON) à conserver côté Mobupay. Retournées dans les webhooks. Utile pour idempotence et metadata interne.