@taramoney/react-sdk

SDK React officiel pour intégrer les paiements Tara Money dans ton application React ou Next.js.

« Intègre en 8 minutes. 3 lignes de code. Dors tranquille. » — La promesse Tara aux devs.

Installation

npm install @taramoney/react-sdk
# ou
yarn add @taramoney/react-sdk

Gérer le CORS — choisis ton setup

Le SDK fait des appels HTTP vers https://www.dklo.co/api/tara. Comme le SDK tourne dans le navigateur, tu dois gérer le CORS. Choisis l'option qui correspond à ton projet :

Option 1 : Next.js (App Router) ✅ Recommandé

Crée un fichier dans ton projet et ré-exporte le handler fourni par le SDK :

// app/api/tara-proxy/route.ts
export { GET, POST, PUT, DELETE } from "@taramoney/react-sdk/server";

Puis active le proxy dans ta config :

<TaraProvider config={{
  apiKey: "ta_clé",
  businessId: "ton_id",
  environment: "production",
  useProxy: true,   // ← Active le proxy Next.js
}}>

Pourquoi ça marche : Les requêtes passent par ton serveur Next.js (pas de CORS), qui les forwarde vers dklo.co.

Option 2 : React pur / Vite / CRA — avec le micro-proxy du SDK

Lance le proxy standalone fourni avec le package :

npx @taramoney/react-sdk proxy
# → Proxy sur http://localhost:3001

Puis configure le SDK :

<TaraProvider config={{
  apiKey: "ta_clé",
  businessId: "ton_id",
  baseUrl: "http://localhost:3001/api/tara",  // ← Le proxy local
  useProxy: false,  // Le proxy gère déjà CORS
}}>

Tu peux changer le port : npx @taramoney/react-sdk proxy --port 8080

Option 3 : Vite (vite.config.ts) — proxy natif

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      "/api/tara": {
        target: "https://www.dklo.co",
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api\/tara/, "/api/tara"),
      },
    },
  },
});

<TaraProvider config={{
  apiKey: "ta_clé",
  businessId: "ton_id",
  baseUrl: "/api/tara",  // Le proxy Vite
  useProxy: false,
}}>

Option 4 : Backend custom / Pas de proxy

Si ton API backend est déjà configurée avec les headers CORS pour ton domaine, tu peux appeler dklo.co directement :

<TaraProvider config={{
  apiKey: "ta_clé",
  businessId: "ton_id",
  baseUrl: "https://www.dklo.co/api/tara",  // Direct
  useProxy: false,
}}>

Quickstart

import { TaraProvider, PayButton, QrCode } from "@taramoney/react-sdk";

function App() {
  return (
    <TaraProvider
      config={{
        apiKey: "ta_clé_publique",
        businessId: "ton_business_id",
        environment: "production",
        useProxy: true, // Si tu utilises Next.js
      }}
    >
      <PayButton
        amount={5000}
        collectionName="collecte_scolaire"
        onSuccess={(tx) => console.log("Payé !", tx)}
      >
        Payer 5000 FCFA
      </PayButton>

      <QrCode collectionId="06706" amount={4000} size={256} />
    </TaraProvider>
  );
}

Composants

| Composant | Description | |-----------|-------------| | TaraProvider | Contexte obligatoire — fournit apiKey, businessId, client | | PayButton | Bouton → modale de paiement (choix réseau + téléphone) | | QrCode | QR code scannable pour WhatsApp/Telegram | | EmbedPay | Intègre la page de paiement complète en iframe | | PaymentForm | Formulaire complet (réseau, téléphone, montant) | | TransactionStatus | Badge de statut avec polling automatique | | useTara() | Hook d'accès au contexte + client HTTP |

API

TaraProvider

| Prop | Type | Défaut | Description | |------|------|--------|-------------| | config.apiKey | string | — | Clé publique Tara | | config.businessId | string | — | Identifiant business | | config.environment | "sandbox" \| "production" | "sandbox" | Environnement | | config.baseUrl | string | "https://www.dklo.co/api/tara" | URL de l'API | | config.qrBaseUrl | string | "https://taramoney.com/pay/" | URL de base pour les liens QR | | config.useProxy | boolean | false | Router via /api/tara-proxy |

PayButton

| Prop | Type | Obligatoire | Description | |------|------|-------------|-------------| | amount | number | Oui | Montant en FCFA | | collectionName | string | Oui | Nom de la collecte | | productId | string | Non | ID produit (généré si absent) | | onSuccess | (tx: Transaction) => void | Non | Callback succès | | onError | (err: Error) => void | Non | Callback erreur | | variant | "primary" \| "outline" | "primary" | Style | | disabled | boolean | false | Désactivé | | children | ReactNode | "Payer X FCFA" | Contenu | | className | string | — | Classe CSS |

QrCode

Génère un QR code qui encode un lien de paiement au format https://taramoney.com/pay/{collectionId}?p={amount}.

| Prop | Type | Défaut | Description | |------|------|--------|-------------| | collectionId | string | — | Identifiant de la collecte (obligatoire) | | amount | number | — | Montant en FCFA (optionnel) | | size | number | 256 | Taille en px | | qrBaseUrl | string | "https://taramoney.com/pay/" | URL de base du lien de paiement |

EmbedPay

Intègre la page de paiement Tara directement dans ton app via une iframe. L'URL générée est :

https://taramoney.com/pay/{collectionId}?p={amount}&accent=ff4400&bg=faf9f7&text=1a1a1a&isFrame=true

La page de paiement applique ces couleurs comme thème visuel et passe en mode embed (layout simplifié, sans ConsentScreen ni QrPaymentCard).

| Prop | Type | Défaut | Description | |------|------|--------|-------------| | collectionId | string | — | Identifiant de la collecte (obligatoire) | | amount | number | — | Montant en FCFA (optionnel) | | payBaseUrl | string | "https://taramoney.com/pay/" | URL de base de la page de paiement | | accentColor | string | "ff4400" | Couleur d'accentuation (hex sans #) | | backgroundColor | string | "faf9f7" | Couleur de fond (hex sans #) | | textColor | string | "1a1a1a" | Couleur du texte (hex sans #) | | height | number \| string | 600 | Hauteur de l'iframe | | width | number \| string | "100%" | Largeur de l'iframe | | onSuccess | (data) => void | — | Callback après paiement réussi | | onError | (error) => void | — | Callback après erreur | | className | string | — | Classe CSS additionnelle |

import { EmbedPay } from "@taramoney/react-sdk";

// Sans TaraProvider — pas besoin de clé API pour l'iframe
<EmbedPay
  collectionId="06706"
  amount={4000}
  accentColor="ff4400"
  backgroundColor="ffffff"
  textColor="1a1a1a"
  onSuccess={(data) => console.log("Payé !", data)}
/>

PaymentForm

| Prop | Type | Description | |------|------|-------------| | amount | number | Montant (optionnel = libre) | | collectionName | string | Collecte | | onSuccess / onError | callback | Callbacks | | webhookUrl | string | URL webhook |

TransactionStatus

| Prop | Type | Défaut | Description | |------|------|--------|-------------| | reference | string | — | Référence transaction | | pollInterval | number | 5000 | Intervalle polling (ms) | | onStatusChange | callback | — | Notifié à chaque changement |

Types

interface Transaction {
  reference: string;
  amount: number;
  status: "SUCCESS" | "PENDING" | "FAILED";
  phoneNumber: string;
  productId?: string;
  createdAt: string;
}

interface TaraConfig {
  apiKey: string;
  businessId: string;
  environment?: "sandbox" | "production";
  baseUrl?: string;
  qrBaseUrl?: string;
  useProxy?: boolean;
}

Réseaux

| Code | Réseau | |------|--------| | ORANGE_CAMEROON | Orange Cameroun | | MTN_CAMEROON | MTN Cameroun |

Licence

MIT © 2026 Tara Écosystème