@ariary/transfer

SDK TypeScript pour l'API de transfert Ariary. Permet de gérer facilement les transactions de transfert d'argent via l'API Ariary.

Installation

npm install @ariary/transfer
# ou
yarn add @ariary/transfer

Configuration

Avant d'utiliser le SDK, vous avez besoin des identifiants d'authentification fournis par Ariary :

• projectId - ID unique de votre projet
• secretId - Clé secrète de votre projet
• baseUrl (optionnel) - URL de base de l'API (par défaut : https://back.ariari.mg/payment)

Utilisation

Initialisation

import { TransferSdk } from '@ariary/transfer';

const sdk = new TransferSdk({
  projectId: 'votre_project_id',
  secretId: 'votre_secret_id',
  baseUrl: 'https://back.ariari.mg/payment' // optionnel
});

Envoyer une transaction

Envoyez de l'argent à un numéro de téléphone :

const response = await sdk.transfer.send('+261322123456', 10000);

console.log(response);
// {
//   id: 'txn_123456',
//   phone: '+261322123456',
//   amount: 10000,
//   status: 'pending',
//   message: 'Transaction créée',
//   requestId: 'req_123',
//   projectId: 'your_project_id',
//   secretId: 'your_secret_id',
//   createdAt: '2025-01-24T10:30:00Z'
// }

Paramètres :

• phone (string) - Numéro de téléphone du destinataire (format international recommandé)
• amount (number) - Montant en unité de devise de l'API (généralement en ariary)

Retour :

• Objet SendTransactionResponse contenant les détails de la transaction

Récupérer toutes les transactions

Récupérez l'historique de toutes les transactions :

const transactions = await sdk.transfer.getAll();

console.log(transactions);
// [
//   {
//     id: 'txn_123456',
//     phone: '+261322123456',
//     amount: 10000,
//     status: 'completed',
//     message: 'Transaction réussie',
//     requestId: 'req_123',
//     projectId: 'your_project_id',
//     secretId: 'your_secret_id',
//     createdAt: '2025-01-24T10:30:00Z'
//   },
//   // ... autres transactions
// ]

Retour :

• Tableau d'objets SendTransactionResponse

Types

SendTransactionResponse

Réponse retournée après l'envoi d'une transaction ou lors de la récupération de transactions.

interface SendTransactionResponse {
  id: string;                  // ID unique de la transaction
  phone: string;               // Numéro de téléphone du destinataire
  amount: number;              // Montant de la transaction
  status: string;              // Statut (pending, completed, failed, etc.)
  message: string;             // Message descriptif
  requestId: string;           // ID de la requête
  projectId: string;           // ID du projet
  secretId: string;            // ID secret du projet
  createdAt: string;           // Date/heure de création (ISO 8601)
}

SendTransactionDto

Structure de données pour créer une transaction (utilisée en interne).

interface SendTransactionDto {
  phone: string;    // Numéro de téléphone du destinataire
  amount: number;   // Montant à transférer
}

ApiConfig

Configuration du SDK.

interface ApiConfig {
  projectId: string;          // ID du projet (requis)
  secretId: string;           // Clé secrète (requis)
  baseUrl?: string;           // URL de base de l'API (optionnel)
}

Gestion des erreurs

Le SDK utilise axios pour les requêtes HTTP. Les erreurs sont propagées tel quelles :

import axios from 'axios';

try {
  const response = await sdk.transfer.send('+261322123456', 10000);
  console.log('Succès:', response);
} catch (error) {
  if (axios.isAxiosError(error)) {
    console.error('Erreur HTTP:', error.response?.status, error.response?.data);
  } else {
    console.error('Erreur:', error);
  }
}

Architecture

Le SDK est organisé en modules :

• TransferSdk - Point d'entrée principal du SDK
• ApiClient - Client HTTP responsable des requêtes
• TransferService - Service métier pour les opérations de transfert
• Types - Définitions TypeScript des interfaces

Exemples complets

Exemple 1 : Envoyer une transaction simple

import { TransferSdk } from '@ariary/transfer';

async function sendMoney() {
  const sdk = new TransferSdk({
    projectId: 'my_project',
    secretId: 'my_secret'
  });

  try {
    const result = await sdk.transfer.send('+261322123456', 5000);
    console.log('Transaction envoyée:', result.id);
    console.log('Statut:', result.status);
  } catch (error) {
    console.error('Erreur lors de l\'envoi:', error);
  }
}

sendMoney();

Exemple 2 : Récupérer et filtrer les transactions

import { TransferSdk } from '@ariary/transfer';

async function listTransactions() {
  const sdk = new TransferSdk({
    projectId: 'my_project',
    secretId: 'my_secret'
  });

  const transactions = await sdk.transfer.getAll();

  // Filtrer les transactions réussies
  const completed = transactions.filter(t => t.status === 'completed');

  // Calculer le total transféré
  const total = transactions.reduce((sum, t) => sum + t.amount, 0);

  console.log(`Total transféré: ${total} ariary`);
  console.log(`Transactions réussies: ${completed.length}`);
}

listTransactions();

Exemple 3 : Utilisation en production

import { TransferSdk } from '@ariary/transfer';

const sdk = new TransferSdk({
  projectId: process.env.ARIARY_PROJECT_ID || '',
  secretId: process.env.ARIARY_SECRET_ID || '',
  baseUrl: process.env.ARIARY_API_URL
});

export async function transferToUser(phone: string, amount: number) {
  try {
    const transaction = await sdk.transfer.send(phone, amount);

    return {
      success: true,
      transactionId: transaction.id,
      status: transaction.status
    };
  } catch (error) {
    console.error(`Erreur lors du transfert vers ${phone}:`, error);
    return {
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error'
    };
  }
}

Variables d'environnement

Pour la sécurité, stockez vos identifiants dans des variables d'environnement :

ARIARY_PROJECT_ID=your_project_id
ARIARY_SECRET_ID=your_secret_id
ARIARY_API_URL=https://back.ariari.mg/payment

Puis utilisez-les :

const sdk = new TransferSdk({
  projectId: process.env.ARIARY_PROJECT_ID || '',
  secretId: process.env.ARIARY_SECRET_ID || '',
  baseUrl: process.env.ARIARY_API_URL
});

Support

Pour toute question ou problème, contactez le support Ariary ou consultez la documentation officielle de l'API.

License

ISC

Auteur

Ariary