Encaisser pour un client, de l'invitation au premier paiement

Une clé sk_int_* invite votre client et retire la clé que vous détenez pour lui ; c'est elle qui encaisse, avec votre commission. Voici l'ordre des appels, et comment tout recetter en simulation.

1. Déclarer votre adresse de réception

Les événements integrator.* partent vers les adresses de votre espace, dans l'environnement de votre clé. Déclarez-en une en test avant tout le reste : la simulation vous enverra les mêmes notifications que la production.

post/api/v1/integrator/webhooks

{
  "url": "https://app.votre-logiciel.nc/webhooks/mobupay",
  "events": ["integrator.client.onboarding.updated", "integrator.client.key.available", "integrator.client.unlinked"]
}

2. Inviter le client

deliveryMode: redirect vous rend le lien à transmettre ; email le fait envoyer par Mobupay. Le préremplissage ne porte que l'identité commerciale : votre client constitue seul son dossier.

Votre externalRef revient dans chaque événement : c'est elle qui rapproche, sans table de correspondance.

post/api/v1/integrator/clients/invitations

{
  "contactEmail": "gerant@lebonplat.nc",
  "deliveryMode": "redirect",
  "redirectUrl": "https://app.votre-logiciel.nc/mobupay/retour",
  "externalRef": "etab_00412",
  "prefill": { "brandName": "Le Bon Plat" }
}

Sans autorisation, pas de clé

À la soumission de son dossier, votre client coche l'autorisation donnée à votre logiciel. S'il ne la donne pas, son compte ouvre quand même, mais aucune clé n'est générée pour vous : integrator.client.opened porte consented: false.

3. En test, mener la simulation jusqu'à l'ouverture

Avec une clé sk_int_test_, l'invitation est simulée. Faites-la avancer jusqu'à open_account : Mobupay crée un compte de test pour votre client, et une clé sk_test_ que vous détenez, rendue dans heldKey (identifiant et préfixe, jamais le secret).

post/api/v1/integrator/clients/invitations/{invitationId}/simulation

{ "transition": "open_account" }

4. Retirer la clé détenue

integrator.client.key.available annonce la clé sans son secret. Retirez-le avec votre clé d'intégrateur du même environnement, et conservez-le comme n'importe quel secret.

post/api/v1/integrator/clients/{merchantId}/api-keys/{keyId}/reveal

{ "keyId": "key_8Lp2mXv5Hq", "prefix": "sk_live_3f9a1c2b", "environment": "live", "secret": "sk_live_…" }

5. Encaisser, avec votre commission

Avec la clé détenue, créez la session de paiement comme n'importe quel marchand, et ajoutez order.integratorCommission. Elle est servie la dernière, après les frais Mobupay, et ne dépasse jamais ce qui reste du paiement.

post/api/v1/payments/sessions

{
  "order": {
    "reference": "CMD-1042",
    "amount": 12000,
    "currency": "XPF",
    "integratorCommission": { "type": "PERCENTAGE", "value": 200 }
  },
  "redirectUrl": "https://app.votre-logiciel.nc/retour",
  "notificationUrl": "https://app.votre-logiciel.nc/webhooks/mobupay"
}

La clé d'intégrateur n'encaisse jamais

Une session créée avec sk_int_* répond 403 INTEGRATOR_KEY_OWN_ROUTES_ONLY, et integratorCommission présenté avec une autre clé que la clé détenue 422 INTEGRATOR_COMMISSION_NOT_ALLOWED.

6. Suivre vos commissions

GET /api/v1/integrator/commissions rend, paiement par paiement, le dû, le prélevé et le reste. Un prélèvement partiel est annoncé par integrator.commission.shortfall, et le reste repris sur les encaissements suivants ; sur un remboursement, votre commission vous reste acquise : vous seul pouvez en rendre une part à votre client, en remboursant avec la clé que vous détenez (restitutedAmount, rien à défaut), et integrator.commission.restituted vous l'annonce.