Paiement en magasin (Jèko Box)

Encaisser au comptoir : un QR code s'affiche sur le terminal, le client le scanne

Vue d'ensemble

Les paiements en magasin passent par un terminal Jèko Box, le boîtier physique posé au comptoir. Un QR code s'y affiche, que le client scanne avec son application de paiement mobile. Dans l'API, ce mode porte le nom de soundbox.

Pour plus de détails : Create payment request (Partner API)

Prérequis

Avant d'intégrer les paiements Jèko Box, vous devez :

Avoir au moins un terminal Jèko Box configuré dans votre compte
Connaître l'identifiant du terminal (deviceId)
Avoir un magasin associé au terminal

Récupérer les terminaux 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",
    "name": "Caisse 1",
    "storeId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
    "storeName": "Magasin Principal"
  }
]

Créer une demande de paiement Jèko Box

Pour créer une demande de paiement Jèko Box, utilisez l'endpoint avec le type soundbox.

Paramètres requis

storeId : Identifiant du magasin
amountCents : Montant en centimes, multiple de 100 (minimum 100)
currency : Code devise (ISO 4217), généralement "XOF"
reference : Référence unique du paiement (5 à 100 caractères)
paymentDetails.type : "soundbox"
paymentDetails.data.deviceId : Identifiant du terminal Jèko Box (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",
  "redirectUrl": "https://pay.jeko.africa/pay_request/pr/d22c81f3-ee04-4ec5-8bd2-cd8af5dabcfc",
  "errorReason": null
}

Vous n'avez rien à afficher. Le QR code apparaît automatiquement sur le terminal du magasin dès que la demande est créée. Conservez l'id retourné : il vous servira à suivre le paiement.

Flux de paiement

Créer la demande : Créez une demande de paiement Jèko Box avec le deviceId
Affichage automatique : Le QR code est automatiquement affiché sur le terminal Jèko Box
Scan client : Le client scanne le QR code avec son application de paiement mobile
Confirmation : Le client confirme le paiement dans son application
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 Jèko Box, 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

Vérifier le terminal : Assurez-vous que le deviceId existe et est actif avant de créer une demande
Références uniques : Utilisez des références uniques pour chaque paiement pour faciliter le suivi
Gérer les erreurs : Implémentez une gestion d'erreurs pour les cas où le terminal n'est pas disponible
Webhooks : Utilisez les webhooks pour être notifié automatiquement des changements de statut
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 Jèko Box
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 terminal est en ligne et connecté
Vérifiez que le terminal 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

Et ensuite

Suivre un paiement : webhook ou interrogation de l'API
Gérer les échecs : chaque erreur et quoi en faire

On this page