Code marchand et points QR

Le QR GIMAC permet aux clients de la zone CEMAC de payer en scannant un code marchand depuis l'application de leur banque ou opérateur. Les routes de points QR permettent de créer un code distinct pour chaque caisse, station, agence ou pompiste.

Parcours de paiement

Le client scanne le QR, saisit le montant en XAF puis valide dans son application de paiement. GIMAC interroge Kratos Pay en temps réel.
Si le code marchand, le compte et le point sont actifs et que le KYC requis est validé, le paiement est accepté immédiatement : la transaction est créée au statut success, le solde est crédité et le webhook est envoyé.
En cas de refus, le client n'est pas débité. Le paiement peut venir d'un autre pays de la zone CEMAC ; le montant reste en XAF.
Les paiements QR sont statiques : le client saisit le montant. Un compte possède déjà un code marchand attribué automatiquement ; demandez au support sa carte imprimable « Scannez & Payez ».

Routes des points QR

Route	Rôle
`POST /gimac/qr-points`	Créer un point avec son code marchand, `qr_payload` et `qr_svg`.
`GET /gimac/qr-points`	Lister les points ; filtres facultatifs `external_ref` et `is_active`. L'image QR n'est pas incluse.
`GET /gimac/qr-points/{uuid}`	Lire un point et son image `qr_svg`.
`PATCH /gimac/qr-points/{uuid}`	Modifier le nom, la ville ou l'application, ou activer/désactiver le point. Le code reste inchangé.
`GET /gimac/qr-points/{uuid}/card`	Ouvrir la carte A5 imprimable avec le nom, le code et le QR.

Pour les routes ci-dessus, utilisez une clé API et X-Application-ID. Les mêmes opérations sont disponibles depuis le dashboard avec un jeton de session sous /merchant/gimac/qr-points.

Créer un point QR

POST/gimac/qr-pointsClé API + X-Application-ID

Crée un code pour une station, un pompiste, une agence ou une caisse. Les paiements sont crédités au solde de l'application indiquée, ou à celle de X-Application-ID si application_id n'est pas fourni.

Corps de la requête

{
  "name": "STATION TOTAL BONAMOUSSADI",
  "city": "Douala",
  "external_ref": "station-42",
  "application_id": 12
}

Réponse 201

{
  "success": true,
  "data": {
    "uuid": "0190b6f0-7a52-7e0a-9b5c-2f6d1c3a8e44",
    "code": "612345",
    "name": "STATION TOTAL BONAMOUSSADI",
    "city": "Douala",
    "external_ref": "station-42",
    "application_id": 12,
    "is_active": true,
    "qr_payload": "00020101021135370014A000000656101001051402302066123455204...",
    "qr_svg": "<svg>…</svg>",
    "created_at": "2026-11-11T09:00:00Z",
    "updated_at": "2026-11-11T09:00:00Z"
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Code	Quand
200	`external_ref` existe déjà : le point existant est renvoyé (création idempotente).
401	Clé API invalide.
422	`name` manquant ou supérieur à 25 caractères, `city` supérieur à 15 caractères, ou `application_id` appartenant à un autre compte.

external_ref est votre identifiant métier stable ; renvoyez la même valeur après un timeout pour éviter un doublon. Le code marchand à 6 chiffres ne change pas.
name (25 caractères max.) et city (15 max.) sont imprimés dans le QR. Les accents sont retirés ; par défaut, city reprend l'adresse du profil.
qr_svg est l'image complète à afficher ou enregistrer ; qr_payload est la chaîne à encoder si vous dessinez vous-même le QR. Ils ne sont pas inclus dans la liste.

Gérer un point et traiter un paiement

PATCH/gimac/qr-points/{uuid}Clé API + X-Application-ID

Corps de la requête

{
  "is_active": false
}

La désactivation fait refuser les paiements scannés sur ce QR ; envoyez is_active: true pour le réactiver. La réponse reprend la structure de création avec les valeurs modifiées. Une erreur 404 indique un point absent ou rattaché à un autre compte. Un changement de nom ou de ville ne modifie pas les QR déjà imprimés.

Webhook `transaction.success` pour un paiement sur un point

{
  "event": "transaction.success",
  "data": {
    "uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
    "type": "collection",
    "provider": "gimac",
    "status": "success",
    "amount": 5000,
    "currency": "XAF",
    "external_id": "C1452HG78511",
    "metadata": {
      "gimac_intent": "merchant_purchase",
      "gimac_frommember": "32001",
      "qr_point_uuid": "0190b6f0-7a52-7e0a-9b5c-2f6d1c3a8e44",
      "qr_point_ref": "station-42",
      "qr_point_name": "STATION TOTAL BONAMOUSSADI"
    }
  }
}

Utilisez metadata.qr_point_ref (votre external_ref) pour attribuer le paiement à la station ou au pompiste. Pour le QR de compte, les champs qr_point_* sont absents.
external_id identifie le transfert GIMAC ; un même transfert n'est jamais crédité deux fois. Les paiements QR ne sont pas remboursables par API.

Conditions et limites

Le marchand entreprise doit être validé KYC pour recevoir des paiements QR ; le particulier en est dispensé.
Disponible en XAF dans la zone CEMAC. Un compte ou un point inactif est refusé et le client n'est pas débité.
Le client saisit le montant lui-même. Les montants fixes par point QR ne sont pas disponibles.