nita_transfert_sdk

SDK Dart officiel des APIs partenaires NITA (v2).

Il couvre l'authentification, la signature HMAC et les quatre produits : Partenaire → Cash (P2CASH), Partenaire → Wallet (P2W), Envoi inter-partenaire (P2P) et Achat en ligne.

Usage serveur uniquement. Le SDK exige la clé API, le login, le mot de passe et le secret HMAC du partenaire. Embarqués dans une application mobile (Flutter) ou dans du code exécuté dans un navigateur, ils peuvent être extraits par n'importe quel utilisateur, qui pourrait alors initier des paiements au nom du partenaire. Une application mobile ou un site doit appeler le serveur du partenaire, qui seul appelle NITA.

Installation

dart pub add nita_transfert_sdk:^0.1.0-beta.1

Démarrage

NitaClient est une couche mince au-dessus du client généré. Elle obtient le jeton, le renouvelle avant expiration, signe chaque requête et décode l'enveloppe de réponse.

import 'dart:io';

import 'package:nita_transfert_sdk/api.dart';
import 'package:nita_transfert_sdk/nita_client.dart';

Future<void> main() async {
  final env = Platform.environment;
  final nita = await NitaClient.connect(
    baseUrl: env['NITA_BASE_URL'], // URL indiquée dans votre espace partenaire
    apiKey: env['NITA_API_KEY']!,
    login: env['NITA_LOGIN']!,
    password: env['NITA_PASSWORD']!,
    hmacSecret: env['NITA_HMAC_SECRET'],
  );

  try {
    final envoi = unwrap<TransactionResponseV2>(await nita.transactions.partenaireToCash(
      PartenaireToCashDtoV2(
        nom: 'Gadjan', prenom: 'Hadi', indicatif: '00227', numero: '92969858',
        requestId: newRequestId('p2c'), fraisInclus: false, montant: 5000,
        villeDestination: 'Niamey', nomDestinataire: 'Woessou', prenomDestinataire: 'Sofiane',
        indicatifDestinataire: '00227', numeroDestinataire: '90111213',
        motifTransaction: 'Paiement',
      ),
    ));
    print(envoi.codeEnvoi);
  } on NitaError catch (e) {
    print('${e.status} ${e.code} ${e.message}');
  }
}

unwrap renvoie le champ data de la réponse, ou lève NitaError quand NITA répond par une erreur métier.

Les autres produits suivent la même forme : nita.transactions, nita.achat, nita.p2p, ainsi que nita.compte, nita.localites, nita.checkStatus et nita.myNita.

Chaque appel HTTP (authentification, rafraîchissement du jeton, appels des APIs) expire après 30 s et lève alors une TimeoutException (enveloppée dans une ApiException pour les appels des APIs). Paramètre timeoutSeconds de connect() pour changer ce délai.

Vérifier un callback

NITA notifie votre urlCallback par un POST JSON signé avec votre secret HMAC (mêmes en-têtes X-NT-*). verifyCallback contrôle la signature, l'horodatage (tolérance 300 s) et renvoie le corps ; elle lève NitaCallbackError sinon.

La signature porte sur le corps brut : passez-le tel que reçu, sans le décoder puis le ré-encoder en JSON.

import 'dart:convert';
import 'dart:io';

import 'package:nita_transfert_sdk/nita_client.dart';

Future<void> handleCallback(HttpRequest req) async {
  final rawBody = await utf8.decoder.bind(req).join();
  final headers = <String, String>{};
  req.headers.forEach((name, values) => headers[name] = values.first);
  try {
    final payload = await verifyCallback(
      rawBody,
      headers,
      secret: Platform.environment['NITA_HMAC_SECRET']!,
      // Anti-rejeu : true si le nonce est nouveau. nonceStore = votre stockage
      // partagé entre instances (base de données, Redis).
      isNewNonce: (nonce, ttl) => nonceStore.putIfAbsent(nonce, ttl),
    );
    // traiter payload['status'] / payload['transaction_id']
    req.response.statusCode = HttpStatus.ok;
  } on NitaCallbackError {
    req.response.statusCode = HttpStatus.unauthorized;
  }
  await req.response.close();
}

Sans isNewNonce, aucun contrôle anti-rejeu : un callback intercepté peut être renvoyé tant que son horodatage reste dans la tolérance. En production, branchez-le sur un stockage partagé (base de données, Redis).

Mode Test

Le sandbox reproduit le comportement de la production, signature comprise. Pointez baseUrl sur votre environnement de test et utilisez une clé nita_test_….

Licence

Logiciel propriétaire NITA Transfert. Voir LICENSE.