Intégration complète paiement et facturation

Un seul appel encaisse et déclenche l'émission de la facture. Ce qui manque ne fait pas échouer le paiement, et c'est justement le piège.

1. Activer le module Facturation

Espace marchand, Paramètres, puis Facturation. Sans module actif, order.invoicing est accepté et aucune facture n'est produite.

GET /api/v1/billing/settings porte completeness : la liste de ce qui manque pour pouvoir émettre, avec le fondement légal de chaque manque. C'est le meilleur point de départ, tant qu'il n'est pas complet aucune émission ne passera.

2. Déclarer les taxes

Aucun taux n'est codé en dur dans Mobupay : ils vivent en base, par marchand, versionnés par la date du texte qui les fixe.

value s'exprime en centièmes de pourcent : 1100 vaut 11 %, 550 vaut 5,5 %. L'unité est entière pour qu'un taux à décimale n'introduise aucun flottant dans un calcul de montant dû.

post/api/v1/billing/taxes

{
  "label": "TGC 11 %",
  "type": "PERCENTAGE",
  "value": 1100
}

Dès qu'une seule ligne porte son propre taxDetail, celui du document est ignoré pour toutes les lignes. Un panier mixte se déclare donc ligne par ligne, ou pas du tout.

3. Créer la session avec `order.invoicing`

Le destinataire est repris de invoicing.recipient, sinon de buyer, sinon de delivery.address.

operationType est obligatoire (décret 2022-1299) et Mobupay ne le devine pas : les mentions ne sont pas les mêmes entre biens et services.

post/api/v1/payments/sessions

{
  "order": {
    "reference": "CMD-2026-0142",
    "amount": 92130,
    "currency": "XPF",
    "items": [
      { "product": "Prestation de conseil", "quantity": 3, "unitPrice": 25000 }
    ],
    "taxDetail": [{ "id": "TGC11", "type": "PERCENTAGE", "value": 1100 }],
    "invoicing": {
      "enabled": true,
      "send": true,
      "operationType": "SERVICES",
      "recipient": {
        "name": "SARL Le Bon Plat",
        "isBusiness": true,
        "registrationId": "1234567.001",
        "address": {
          "line1": "12 rue de l'Alma",
          "postalCode": "98800",
          "city": "Nouméa",
          "country": "NC"
        }
      }
    }
  },
  "captureMode": "AUTO",
  "redirectUrl": "https://example.com/return",
  "notificationUrl": "https://example.com/webhook"
}

4. Lire ce que la capture répond

En capture MANUAL, la validation et l'émission ont lieu à la capture : c'est là que l'adresse réelle et les frais enfin connus se complètent.

La réponse porte invoicing: { requested, issued, skippedReason?, blockers? }.

Une capture réussit même quand la facture n'est pas émise

Un encaissement acquis n'est pas remis en cause par un document manquant. issued: 0 avec un skippedReason signale ce cas, blockers nommant les champs à compléter. Un intégrateur qui ne lit que le code HTTP croit avoir facturé.

5. Lire la facture émise

GET /api/v1/billing/invoices/{id} rend le document, sa numérotation, sa ventilation de taxes et la disponibilité du PDF archivé.

201, facture