Gestion des contacts bénéficiaires

Les contacts bénéficiaires sont des enregistrements de personnes ou d'entités qui peuvent recevoir des transferts Mobile Money ou bancaires. *Pour ces rails, créez un contact (ou passez un bénéficiaire inline) avant le transfert.*

Kelyko n'est pas une méthode de contact. Un push vers un magasin Kelyko utilise destinationStoreId sur POST /partner_api/transfers — voir Intégration des transferts.

Deux types de contacts

Kelyko supporte deux types de contacts :

1. Contacts Mobile Money : Pour les transferts vers des comptes Mobile Money
2. Contacts bancaires : Pour les transferts vers des comptes bancaires

Créer un contact Mobile Money

Pour créer un contact Mobile Money, vous devez fournir :

• Le nom du bénéficiaire
• La méthode de paiement (wave, orange_money, mtn, moov, djamo)
• Le numéro de téléphone au format international

Exemple : Créer un contact Wave

curl -X POST "https://api.kelyko.invalid/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"
    }
  }'

Exemple : Créer un contact Orange Money

curl -X POST "https://api.kelyko.invalid/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 Smith",
    "paymentMethod": "orange_money",
    "identifier": {
      "number": "+2250501234567"
    }
  }'

Réponse

{
  "id": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
  "name": "John Doe",
  "paymentMethod": "wave",
  "identifier": {
    "number": "+2250701234567"
  }
}

Conservez l'id retourné : c'est le contactId que vous fournirez à chaque transfert vers ce bénéficiaire.

Créer un contact bancaire

Pour créer un contact bancaire, vous devez fournir :

• Le nom du bénéficiaire
• La méthode de paiement : "bank"
• Les détails bancaires complets (RIB)

Détails bancaires requis

• bankName : Nom de la banque
• bankCode : Code de la banque
• swiftCode : Code SWIFT/BIC
• agencyCode : Code de l'agence
• accountNumber : Numéro de compte
• key : Clé RIB

Exemple : Créer un contact bancaire

curl -X POST "https://api.kelyko.invalid/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"
    }
  }'

Réponse

{
  "id": "29f81706-03a6-492f-92ee-5f0b2e9b18e7",
  "name": "Jane Doe",
  "paymentMethod": "bank",
  "identifier": {
    "bankName": "Ecobank",
    "bankCode": "ECO01",
    "swiftCode": "ECOCCIAB",
    "agencyCode": "00123",
    "accountNumber": "0123456789",
    "key": "12"
  }
}

Lister les contacts

Pour récupérer la liste de tous vos contacts bénéficiaires :

curl -X GET "https://api.kelyko.invalid/partner_api/contacts" \
  -H "X-API-KEY: your_api_key_here" \
  -H "X-API-KEY-ID: your_api_key_id_here"

Réponse

[
  {
    "id": "59ae202a-f583-4a15-970f-9e99bd1e0baa",
    "name": "John Doe",
    "paymentMethod": "wave",
    "identifier": {
      "number": "+2250701234567"
    }
  },
  {
    "id": "29f81706-03a6-492f-92ee-5f0b2e9b18e7",
    "name": "Jane Doe",
    "paymentMethod": "bank",
    "identifier": {
      "bankName": "Ecobank",
      "bankCode": "ECO01",
      "swiftCode": "ECOCCIAB",
      "agencyCode": "00123",
      "accountNumber": "0123456789",
      "key": "12"
    }
  }
]

Supprimer un contact

Pour supprimer un contact (suppression douce) :

curl -X DELETE "https://api.kelyko.invalid/partner_api/contacts/{contactId}" \
  -H "X-API-KEY: your_api_key_here" \
  -H "X-API-KEY-ID: your_api_key_id_here"

Note : Après suppression, le contact ne sera plus disponible pour de nouveaux transferts, mais l'historique des transferts précédents reste accessible.

Créez vos contacts à l'avance

1. Créer les contacts à l'avance : Enregistrez vos contacts bénéficiaires avant d'avoir besoin d'effectuer des transferts
2. Valider les informations : Vérifiez que les numéros de téléphone et les détails bancaires sont corrects avant de créer le contact
3. Réutiliser les contacts : Une fois créé, un contact peut être utilisé pour plusieurs transferts
4. Gérer les contacts : Maintenez une liste à jour de vos contacts et supprimez ceux qui ne sont plus nécessaires
5. Stockage sécurisé : Conservez les contactId de manière sécurisée dans votre système pour référence future

Obtenir les codes bancaires

Pour obtenir la liste des banques supportées et leurs codes, utilisez l'endpoint /partner_api/banks :

curl -X GET "https://api.kelyko.invalid/partner_api/banks" \
  -H "X-API-KEY: your_api_key_here" \
  -H "X-API-KEY-ID: your_api_key_id_here"

Cela vous permet de valider les informations bancaires avant de créer un contact bancaire.