Skip to main content

​
Vue d’ensemble

Les paiements en magasin utilisent des terminaux soundbox JEKO physiques. Un QR code est généré et affiché sur le terminal, que le client scanne avec son application de paiement mobile.

​
Prérequis

Avant d’intégrer les paiements soundbox, vous devez :
  • Avoir au moins un dispositif soundbox configuré dans votre compte
  • Connaître l’identifiant du dispositif (deviceId)
  • Avoir un magasin associé au dispositif

​
Récupérer les dispositifs disponibles

curl -X GET "https://api.jeko.africa/partner_api/devices" \
  -H "X-API-KEY: your_api_key_here" \
  -H "X-API-KEY-ID: your_api_key_id_here"
Réponse : 
[
  {
    "id": "DEVICE-ABC123",
    "storeId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
    "storeName": "Magasin Principal"
  }
]

​
Créer une demande de paiement soundbox

Pour créer une demande de paiement soundbox, utilisez l’endpoint /partner_api/payment_requests avec le type soundbox.

​
Paramètres requis

  • storeId : Identifiant du magasin
  • amountCents : Montant en centimes (minimum 100 centimes)
  • currency : Code devise (ISO 4217), généralement “XOF”
  • reference : Référence unique du paiement (1-100 caractères)
  • paymentDetails.type : "soundbox"
  • paymentDetails.data.deviceId : Identifiant du dispositif soundbox (requis)
  • paymentDetails.data.paymentMethod : Méthode de paiement (wave, orange, mtn, moov, djamo)

​
Exemple de requête

curl -X POST "https://api.jeko.africa/partner_api/payment_requests" \
  -H "X-API-KEY: your_api_key_here" \
  -H "X-API-KEY-ID: your_api_key_id_here" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
    "amountCents": 10000,
    "currency": "XOF",
    "reference": "PAY-STORE-2024-001",
    "paymentDetails": {
      "type": "soundbox",
      "data": {
        "deviceId": "DEVICE-ABC123",
        "paymentMethod": "wave"
      }
    }
  }'

​
Réponse réussie

{
  "id": "d22c81f3-ee04-4ec5-8bd2-cd8af5dabcfc",
  "storeId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
  "reference": "PAY-STORE-2024-001",
  "type": "soundbox",
  "paymentMethod": "wave",
  "status": "pending",
  "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}
Important : Le champ qrCode contient le QR code en base64. Ce QR code est automatiquement affiché sur le terminal soundbox, mais vous pouvez également l’utiliser dans votre application si nécessaire.

​
Flux de paiement

  1. Créer la demande : Créez une demande de paiement soundbox avec le deviceId
  2. Affichage automatique : Le QR code est automatiquement affiché sur le terminal soundbox
  3. Scan client : Le client scanne le QR code avec son application de paiement mobile
  4. Confirmation : Le client confirme le paiement dans son application
  5. Notification : Vous recevez une notification via webhook lorsque le paiement est complété

​
Vérifier le statut

Pour vérifier le statut d’une demande de paiement : 
curl -X GET "https://api.jeko.africa/partner_api/payment_requests/{paymentRequestId}" \
  -H "X-API-KEY: your_api_key_here" \
  -H "X-API-KEY-ID: your_api_key_id_here"
Réponse avec transaction réussie : 
{
  "id": "d22c81f3-ee04-4ec5-8bd2-cd8af5dabcfc",
  "storeId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
  "reference": "PAY-STORE-2024-001",
  "type": "soundbox",
  "paymentMethod": "wave",
  "status": "success",
  "transaction": {
    "id": "txn_1234567890",
    "amount": {
      "amount": 10000,
      "currency": "XOF"
    },
    "fees": {
      "amount": 100,
      "currency": "XOF"
    },
    "status": "success",
    "counterpartLabel": "Customer Name",
    "counterpartIdentifier": "+2250701234567",
    "description": "Payment for order #12345",
    "executedAt": "2024-01-15 14:30:25"
  }
}

​
Méthodes de paiement supportées

Pour les paiements soundbox, vous devez spécifier une méthode de paiement :
  • "wave" : Wave Mobile Money
  • "orange" : Orange Money
  • "mtn" : MTN Mobile Money
  • "moov" : Moov Money
  • "djamo" : DJAMO

​
Bonnes pratiques

  1. Vérifier le dispositif : Assurez-vous que le deviceId existe et est actif avant de créer une demande
  2. Références uniques : Utilisez des références uniques pour chaque paiement pour faciliter le suivi
  3. Gérer les erreurs : Implémentez une gestion d’erreurs pour les cas où le dispositif n’est pas disponible
  4. Webhooks : Utilisez les webhooks pour être notifié automatiquement des changements de statut
  5. Expiration : Les demandes de paiement peuvent expirer après un certain temps, prévoyez une gestion des timeouts

​
Cas d’usage

  • Boutiques physiques : Paiements en caisse avec terminal soundbox
  • Restaurants : Paiements à table avec terminal mobile
  • Points de vente : Paiements rapides sans contact

​
Dépannage

​
Le QR code ne s’affiche pas sur le terminal

  • Vérifiez que le deviceId est correct
  • Vérifiez que le dispositif est en ligne et connecté
  • Vérifiez que le dispositif est associé au bon magasin

​
Le paiement reste en “pending”

  • Le client peut ne pas avoir confirmé le paiement dans son application
  • Vérifiez le statut via l’API ou les webhooks
  • Les paiements peuvent prendre quelques minutes à être traités