Documentation J+SERVICES Guides Référence API

Contrat API — Agrégateurs de paiement TiketMOMO

Initier une vente

POST /api/v1/store/sale-init crée une transaction interne PENDING; il ne crée pas la transaction chez le prestataire. Pour MoneyFusion, transmettre provider: "moneyfusion" seulement quand MONEYFUSION_TIKETMOMO_HUB_ENABLED=true; le verrou est désactivé par défaut. Sinon la route répond 503 avec PAYMENT_PROVIDER_DISABLED, l’endpoint n’est pas listé et le webhook hub ne l’accepte pas. Lorsqu’il est activé, le serveur retourne notamment internal_tx_id, le prix corrigé du profil, aggregator_metadata, return_url et une indication de webhook. return_url est une URL de retour navigateur par transaction vers la page de livraison TiketMOMO. La page attend la confirmation serveur avant d’afficher le ticket.

Le montant retourné par le serveur est autoritaire. Ne pas reprendre un montant différent fourni par le routeur ou le client.

Retour navigateur et webhook

Pour MoneyFusion, transmettre data.return_url comme return_url du paiement et data.endpoints.moneyfusion comme webhook_url (obtenu par GET /api/v1/clients/auth/webhook-endpoints). Ce sont deux URLs différentes : le retour navigateur ouvre la page de livraison, tandis que le webhook notifie le serveur. La redirection ne prouve jamais le paiement; seule la confirmation serveur déclenche la livraison. L’hôte de return_url vient de TIKETMOMO_PUBLIC_BASE_URL (défaut https://tpay.mikhmoai.com).

Configurer le webhook tenant

GET /api/v1/clients/auth/webhook-endpoints retourne l’URL personnalisée data.endpoints.moneyfusion. Elle contient le jeton webhook du marchand; la garder confidentielle et la configurer dans l’application MoneyFusion du marchand. Le hub transmet ce jeton au worker, qui vérifie qu’il appartient au vendeur de la transaction en attente.

Le domaine API actuellement configuré est https://live.jmoai.net; le domaine public du paiement MoneyFusion est fourni par le tableau de bord du marchand.

Créer le paiement MoneyFusion

Le marchand crée le paiement auprès de sa propre application MoneyFusion. Le corps doit respecter les champs PAYIN requis (totalPrice, article, numeroSend, nomclient) et inclure les métadonnées de sale-init dans personal_Info, sous forme de tableau. Exemple de forme :

{
  "totalPrice": 100,
  "article": [{ "100F-4H": 100 }],
  "numeroSend": "22990000000",
  "nomclient": "Client",
  "personal_Info": [
    {
      "orderId": "TM_transaction_id",
      "client_id": "manager_id",
      "manager_id": "manager_id",
      "product_code": "tiketmomo",
      "plan_code": "100F-4H",
      "nasid": "identifiant-boutique"
    }
  ],
  "webhook_url": "URL data.endpoints.moneyfusion"
}

En pratique, recopier les valeurs de aggregator_metadata renvoyées par sale-init; ne pas saisir les identifiants d’exemple ci-dessus. L’application MoneyFusion fournit son URL API PAYIN depuis son tableau de bord.

Confirmation et livraison

Le hub traite comme succès uniquement payin.session.completed. Avant de publier l’événement, il appelle l’API de statut MoneyFusion et exige une réponse confirmée, le statut distant paid, le même tokenPay et le même personal_Info[].orderId. Si l’API de vérification est indisponible, le hub répond 503 pour permettre une nouvelle notification; si les données ne confirment pas le paiement, il répond 409.

Le worker vérifie à nouveau la transaction PENDING, le propriétaire/jeton tenant, le NAS et le prix. Le prix doit correspondre à Montant ou à Montant + frais, selon la représentation retournée par MoneyFusion. Les notifications pending et cancelled sont acquittées sans livrer de ticket; elles ne modifient pas encore l’état financier local.

Pour l’événement MoneyFusion, l’identité vendeur, le produit et le NAS consommés par le worker viennent du statut relu chez MoneyFusion; le hub force la branche tiketmomo et ne fait pas confiance à ces métadonnées depuis le seul webhook.

La documentation MoneyFusion ne décrit pas de signature cryptographique du webhook. La protection s’appuie donc sur le jeton tenant dans l’URL, la vérification indépendante du statut et les contrôles aval du worker. Aucun paiement réel ni lancement commercial n’est garanti par la présence de cette intégration dans le code.

Déviations et limites