Intégration des transferts

Vue d'ensemble

Un transfert exige un contact bénéficiaire existant. Si vous n'en avez pas encore créé, commencez par Gestion des contacts bénéficiaires.

Prérequis

Avant de commencer, assurez-vous d'avoir :

Un compte entreprise Jèko configuré
Des clés API générées (voir Authentification)
Au moins un magasin créé (voir Gestion des magasins)
Un contact bénéficiaire enregistré (voir Gestion des contacts bénéficiaires)

Flux d'intégration

Créer un contact bénéficiaire

Si vous n'avez pas encore créé le contact, créez-le d'abord :

# Exemple : Créer un contact Mobile Money
curl -X POST "https://api.jeko.africa/partner_api/contacts" \
  -H "X-API-KEY: your_api_key_here" \
  -H "X-API-KEY-ID: your_api_key_id_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "paymentMethod": "wave",
    "identifier": {
      "number": "+2250701234567"
    }
  }'

Conservez le id retourné (contactId) pour l'étape suivante.

Vérifier le solde du magasin

Avant d'effectuer un transfert, vérifiez que le magasin dispose de fonds suffisants :

curl -X GET "https://api.jeko.africa/partner_api/stores/{storeId}/balance" \
  -H "X-API-KEY: your_api_key_here" \
  -H "X-API-KEY-ID: your_api_key_id_here"

Créer le transfert

Une fois le contact créé et le solde vérifié, créez le transfert :

curl -X POST "https://api.jeko.africa/partner_api/transfers" \
  -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",
    "contactId": "29f81706-03a6-492f-92ee-5f0b2e9b18e7",
    "amountCents": 50000,
    "currency": "XOF",
    "description": "Monthly salary payment",
    "reference": "PAYROLL-APR-001"
  }'

Paramètres requis

storeId : Identifiant du magasin depuis lequel transférer les fonds
contactId : Identifiant du contact bénéficiaire (créé à l'étape 1)
amountCents : Montant en centimes (minimum 500 centimes = 5 XOF)
currency : Code devise (ISO 4217), généralement "XOF"
description : (Optionnel) Description du transfert (max 255 caractères)
reference : (Optionnel) Référence partenaire pour la réconciliation (5 à 100 caractères). Elle doit être unique : si un transfert existe déjà avec la même référence, l’API répond 409 Conflict. Lorsqu’elle est envoyée, elle est renvoyée sur les réponses de l’API et dans transactionDetails.reference des webhooks de transaction liés au transfert.

Réponse réussie

{
  "id": "wth_abc123def456",
  "storeId": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
  "contactId": "29f81706-03a6-492f-92ee-5f0b2e9b18e7",
  "amount": {
    "amount": 50000,
    "currency": "XOF"
  },
  "fees": {
    "amount": 500,
    "currency": "XOF"
  },
  "status": "pending",
  "paymentMethod": "wave",
  "beneficiary": "+2250701234567",
  "description": "Monthly salary payment",
  "reference": "PAYROLL-APR-001",
  "createdAt": "2024-01-15T14:30:25.000Z"
}

Traitement asynchrone

Les transferts sont traités de manière asynchrone. Le statut initial sera pending et évoluera vers success ou error une fois le traitement terminé.

Suivi du statut

Pour suivre l'état d'un transfert, vous pouvez :

Utiliser les webhooks : Configurez un endpoint webhook pour recevoir les notifications de changement de statut
Interroger l'API : Utilisez l'endpoint de liste des transactions pour vérifier le statut

Exemples complets

Exemple 1 : Transfert vers Mobile Money (Wave)

# 1. Créer le contact
CONTACT_RESPONSE=$(curl -X POST "https://api.jeko.africa/partner_api/contacts" \
  -H "X-API-KEY: your_api_key_here" \
  -H "X-API-KEY-ID: your_api_key_id_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "paymentMethod": "wave",
    "identifier": {
      "number": "+2250701234567"
    }
  }')

CONTACT_ID=$(echo $CONTACT_RESPONSE | jq -r '.id')

# 2. Effectuer le transfert
curl -X POST "https://api.jeko.africa/partner_api/transfers" \
  -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\",
    \"contactId\": \"$CONTACT_ID\",
    \"amountCents\": 50000,
    \"currency\": \"XOF\",
    \"description\": \"Salary payment\"
  }"

Exemple 2 : Transfert vers compte bancaire

# 1. Créer le contact bancaire
CONTACT_RESPONSE=$(curl -X POST "https://api.jeko.africa/partner_api/contacts" \
  -H "X-API-KEY: your_api_key_here" \
  -H "X-API-KEY-ID: your_api_key_id_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "paymentMethod": "bank",
    "identifier": {
      "bankName": "Ecobank",
      "bankCode": "ECO01",
      "swiftCode": "ECOCCIAB",
      "agencyCode": "00123",
      "accountNumber": "0123456789",
      "key": "12"
    }
  }')

CONTACT_ID=$(echo $CONTACT_RESPONSE | jq -r '.id')

# 2. Effectuer le transfert
curl -X POST "https://api.jeko.africa/partner_api/transfers" \
  -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\",
    \"contactId\": \"$CONTACT_ID\",
    \"amountCents\": 100000,
    \"currency\": \"XOF\",
    \"description\": \"Supplier payment - Invoice #12345\"
  }"

Gestion des erreurs

Erreurs communes

400 Bad Request : Solde insuffisant ou données invalides
401 Unauthorized : Clés API invalides ou manquantes
404 Not Found : Contact ou magasin introuvable
409 Conflict : Un transfert existe déjà avec la même valeur de reference. Traitez cette réponse comme une protection idempotente ou réutilisez le transfert existant plutôt que de recréer.
422 Unprocessable Entity : Erreur de validation des données

Pour plus de détails sur les raisons d'échec des transferts, consultez Gérer les échecs.

Bonnes pratiques

Créer les contacts en amont : Enregistrez vos contacts bénéficiaires avant d'avoir besoin d'effectuer des transferts
Vérifier le solde : Toujours vérifier le solde disponible avant de créer un transfert
Gérer les erreurs : Prévoyez un traitement pour chaque cas d'échec documenté
Utiliser les webhooks : Configurez des webhooks pour être notifié des changements de statut
Réutiliser les contacts : Une fois créé, un contact peut être utilisé pour plusieurs transferts
Valider les montants : Vérifiez que le montant respecte le minimum (500 centimes) et que vous avez suffisamment de fonds pour couvrir les frais
reference pour l’idempotence : Utilisez une valeur stable par intention de transfert dans votre système pour détecter les doubles envois (409) et faciliter la réconciliation (webhooks inclus)

Intégration avec les webhooks

Pour être notifié des changements de statut des transferts, configurez un endpoint webhook. Consultez la documentation Webhooks pour plus d'informations.

Si vous avez fourni un champ reference à la création du transfert, la même valeur est exposée dans les webhooks de transaction (dans transactionDetails.reference) pour corréler avec votre système interne.

On this page