Capturer un paiement autorisé

Capture un paiement préalablement autorisé en mode MANUAL. Utile pour les plateformes ou les paiements différés (capture après expédition, fin de location...). Capture partielle possible via amountCents (entier strictement positif, inférieur au montant autorisé). Si omis, capture le montant total autorisé.

Définition de l'`order` à la capture : l'objet order peut être défini ou surchargé au moment de la capture, dans la même forme que la session. Pour un paiement de type platform sans split stocké à la création, order.platformConfig est requis ici.

Contexte de la commande : au-delà des champs de calcul (amount, discount, items, taxDetail, tips, platformConfig), la capture accepte le contexte : reference, delivery, buyer, device, invoicing. C'est le moment où ces données existent enfin (adresse de livraison confirmée, frais réels, date de remise), et c'est aussi là que le module Facturation valide et émet, en capture MANUAL. Seuls les champs fournis remplacent l'order initial, et un sous-objet fourni remplace le sous-objet entier (pas de fusion champ par champ). Deux champs sont refusés ici : order.currency (400 ORDER_CURRENCY_IMMUTABLE, l'autorisation carte porte une devise figée) et order.taxAmount (400 ORDER_TAX_AMOUNT_SERVER_COMPUTED, toujours recalculé par Mobupay depuis taxDetail).

Remise financée par la plateforme (« crédits ») : si order.discount est fourni, le montant capturé sur la carte doit être égal à order.amount − order.discount (la carte n'est débitée que du net) et la somme des order.platformConfig[].amount doit être égale à order.amount (le split couvre le total commande). La plateforme abonde alors le complément vers le séquestre.

Promotion financée par la plateforme au-dessus de l'autorisation (top-up) : en mode platform, order.amount peut DÉPASSER le montant autorisé à condition que la remise plateforme couvre l'excédent, pourboires inclus : (order.amount − order.discount) + Σ tips ≤ montant autorisé. Cas d'usage : n'autoriser que le net client à la commande, puis distribuer à la capture le montant plein aux sous-marchands (la plateforme absorbe la promotion). La carte n'est JAMAIS débitée au-delà de l'empreinte : le montant EUR débité est exactement l'EUR déjà autorisé (aucune dérive d'arrondi XPF→EUR, le complément plateforme absorbe la conversion). Sinon → 400 CAPTURE_AMOUNT_EXCEEDS_AUTHORIZED_UNFUNDED. Voir la section Cas d'usage (/docs/usecases/distant/plateforme/cas-particuliers).

Capturer MOINS que le montant autorisé : c'est permis, à condition de dire ce qui est capturé. Redéfinissez l'order avec son détail — order.platformConfig en mode plateforme, order.items en direct — dont les montants doivent totaliser order.amount. Exemple : commande de 5 000 partiellement livrée, on capture 3 000 en envoyant order.amount: 3000 et le platformConfig correspondant. Le débit carte se déduit alors de l'order (amount − discount + Σ tips) : amountCents est facultatif, et s'il est fourni il doit concorder exactement, sinon 400 CAPTURE_AMOUNT_MISMATCH. Le paiement passe en capture partielle et reste re-capturable. Un `order.amount` simplement plus petit, sans détail, est refusé (400 CAPTURE_AMOUNT_BELOW_AUTHORIZED) : une baisse doit être justifiée, jamais muette.

Pourboire non réduit : sur une capture partielle ou un règlement partiel, les pourboires sont versés à leur montant plein et la baisse est absorbée par les parts de marchandise. Un pourboire ne diminue pas parce qu'un article manque.

Pourboire déjà inclus dans l'autorisation : le cas le plus courant, quand vous autorisez le total pourboire compris. Déclarez-le par order.platformConfig[].tips sur l'entrée du sous-marchand qui le reçoit (le livreur), ce qui suppose de le sortir de order.amount. Le brut passe alors sous le montant autorisé, et c'est normal : la couverture est appréciée sur le débit carte, order.amount − order.discount + Σ tips, qui doit égaler exactement l'autorisé. Exemple : empreinte 5 000 (panier 4 000 + livraison 700 + pourboire 300) → order.amount: 4700, platformConfig: [{resto, 4000}, {livreur, 700, tips: 300}]. N'ajoutez jamais le pourboire à l'`amount` de l'entrée : la somme versée serait la même, mais votre commission plateforme se calculerait dessus, alors qu'un pourboire n'est pas commissionné.

E-commerce direct : besoin équivalent déjà couvert sans top-up — order.amount y est le net des remises (amount = Σ items − discounts) : ajoutez des articles avec une remise qui compense en gardant order.amount égal au montant autorisé.