Guide d'intégration

Le concept

Rien ne change pour vos utilisateurs ou votre application

KalyRails expose un endpoint JSON-RPC standard — la même interface utilisée par tous les services compatibles Ethereum dans le monde. Si votre équipe a déjà appelé une API REST, elle peut s'intégrer à KalyRails.

Votre backend devient le pont entre vos utilisateurs et la blockchain. Lorsqu'un utilisateur initie un transfert, votre serveur appelle notre RPC, et la transaction est enregistrée sur votre chaîne ZK privée. L'utilisateur ne sait jamais que la blockchain est impliquée.

Vous pouvez intégrer avec n'importe quel langage — JavaScript, Python, Java, Go, PHP, Ruby. S'il peut faire une requête HTTP, il peut parler à KalyRails.

Ce dont vous avez besoin

01

L'URL de votre endpoint RPC (nous la fournissons)

02

Clé de signature opérateur (nous la générons et la sécurisons ensemble)

03

Un client HTTP dans votre backend (vous en avez déjà un)

Temps d'intégration moyen

1 à 3 jours

Étape par étape

Connecter votre backend

01

Connectez-vous avec votre portefeuille opérateur

Vous exploitez un seul portefeuille de signature dépositaire sur votre chaîne KalyRails — rien de plus. Vos utilisateurs n'ont ni portefeuille, ni adresse, ni clé. Les soldes et l'historique des utilisateurs vivent à l'intérieur du contrat mobile money, indexés par les ID utilisateurs existants de votre base de données.

// Charger votre portefeuille opérateur (à sécuriser comme tout secret d'API)
const { ethers } = require('ethers');

const provider = new ethers.JsonRpcProvider(
  'https://your-chain.kalyrails.io/rpc'  // Nous vous fournissons cette URL
);

const operatorWallet = new ethers.Wallet(
  process.env.KALYRAILS_OPERATOR_KEY,
  provider
);

// Se connecter au contrat mobile money (adresse fournie à l'onboarding)
const mobileMoney = new ethers.Contract(
  MOBILE_MONEY_CONTRACT,
  abi,
  operatorWallet
);
      

02

Soumettez des transferts par ID utilisateur

Lorsqu'un utilisateur initie un transfert, votre backend appelle directement le contrat mobile money avec les ID utilisateurs de l'expéditeur et du destinataire provenant de votre base de données. Le contrat valide les limites, déduit des frais en KUSD vers votre trésorerie de revenus et enregistre le transfert de manière immuable — le tout dans une seule transaction signée par votre portefeuille opérateur.

async function sendTransfer(fromUserId, toUserId, amountMinorUnits) {
  // Appel de la fonction de transfert dépositaire.
  // Le portefeuille opérateur est le seul signataire — vos ID utilisateurs sont les arguments.
  const tx = await mobileMoney.transfer(
    fromUserId,     // votre ID utilisateur interne (uint256)
    toUserId,       // votre ID utilisateur interne (uint256)
    amountMinorUnits // montant dans la plus petite unité (ex. centimes)
  );
  const receipt = await tx.wait();

  // Stocker le hash on-chain comme preuve immuable du transfert
  return {
    txHash: receipt.hash,
    blockNumber: receipt.blockNumber,
    feeCollected: receipt.logs /* événement KUSDFee */
  };
}

// Dans votre endpoint de transfert existant :
app.post('/transfer', async (req, res) => {
  const { fromUserId, toUserId, amount } = req.body;
  const proof = await sendTransfer(fromUserId, toUserId, amount);
  await db.saveTransferProof(req.body.transferRef, proof.txHash);
  res.json({ success: true, proof });
});
      

03

Interrogez soldes et historique par ID utilisateur

Les soldes des utilisateurs vivent à l'intérieur du contrat mobile money sous forme de mapping entre votre ID utilisateur et un solde. Lisez-les directement avec un appel de type view, ou utilisez l'API de l'explorateur de blocs pour des requêtes plus riches et des pistes d'audit prêtes pour les régulateurs.

// Vérifier le solde d'un utilisateur directement on-chain
const balance = await mobileMoney.balanceOf(userId);

// Ou utiliser l'API Explorer pour l'historique de transactions par ID utilisateur
const history = await fetch(
  `https://explorer.kalyrails.io/api/user/${userId}/transfers`
);
const txns = await history.json();

// Afficher dans votre application — les utilisateurs voient leur liste de transactions habituelle
txns.items.forEach(tx => {
  renderTransaction({
    amount: tx.amount,
    counterparty: resolveUserName(tx.counterpartyUserId),
    date: tx.timestamp,
    status: tx.confirmed ? 'complete' : 'pending',
    blockchainProof: tx.txHash  // Pour un audit vérifiable par les régulateurs
  });
});
      

Compatibilité

Fonctionne avec toute pile backend

KalyRails utilise l'interface JSON-RPC Ethereum standard. Chaque langage majeur possède des bibliothèques prêtes à l'emploi.

JS

JavaScript / Node.js

ethers.js, web3.js, viem

PY

Python

web3.py, brownie

☞

Java / Kotlin

web3j

GO

Go

go-ethereum (geth)

PH

PHP

web3.php

🔸

N'importe quel langage

Appels HTTP/JSON-RPC bruts

Ce que vous obtenez

Chaque intégration inclut

Contrats intelligents pré-construits

Contrats de transfert mobile money, contrats de commission d'agent, contrats de règlement marchand — éprouvés et auditables. Couvrent 80 % des cas d'usage dès la sortie. Contrats sur mesure disponibles pour les plans Growth et Enterprise.

SDK et exemples de code

Exemples de code prêts à l'emploi en JavaScript, Python et Java montrant exactement comment mapper les utilisateurs, soumettre des transferts, interroger des soldes et gérer les événements. Copier, coller, adapter à votre pile.

Environnement de testnet

Une chaîne de staging complète où vous pouvez tester votre intégration sans impacter la production. Même API, mêmes contrats, même comportement — mais avec des tokens de test pour que rien de réel ne soit en jeu.

Support d'intégration

Notre équipe d'ingénierie vous accompagne dans l'intégration. Nous revoyons votre code, répondons aux questions et aidons au débogage. La plupart des intégrations passent du premier appel API à la production en 1 à 3 jours.

Questions fréquentes

FAQ intégration

Avons-nous besoin de développeurs blockchain dans notre équipe ?

Non. Si votre équipe peut faire des appels d'API HTTP, elle peut s'intégrer à KalyRails. L'interface RPC est identique à n'importe quelle API REST. Le développement des contrats intelligents et l'infrastructure blockchain sont entièrement pris en charge par nous.

Et si notre backend utilise un langage que vous n'avez pas listé ?

KalyRails utilise JSON-RPC standard sur HTTP. Si votre langage peut envoyer une requête HTTP POST avec un corps JSON, il peut parler à KalyRails. Aucune bibliothèque spéciale n'est requise.

Pouvons-nous fonctionner en parallèle de notre base de données existante ?

Absolument. La plupart des clients conservent leur base de données existante pour la gestion des utilisateurs, le KYC, l'état de l'application, etc. et ajoutent KalyRails comme couche de règlement. Votre base de données reste votre source de vérité pour la logique applicative — la blockchain ajoute une preuve immuable de chaque transaction financière.

Que se passe-t-il si la chaîne ZK tombe en panne ?

Votre application continue de fonctionner. Vous pouvez mettre les transactions en file d'attente localement et les soumettre lorsque la chaîne récupère. Toutes les données sont également stockées dans une base de données PostgreSQL gérée avec sauvegardes automatiques. Notre SLA garantit une disponibilité de 99,9 % sur les plans Growth et Enterprise.

Comment s'intègrent les applications basées sur l'USSD ?

Les interfaces USSD parlent à votre serveur backend, qui parle à KalyRails via JSON-RPC. Le point d'intégration est votre backend — pas le téléphone de l'utilisateur. Que vos utilisateurs soient sur une application smartphone, en USSD ou même en SMS, l'intégration blockchain est la même.

Connectez votre backend existant en heures, pas en mois