> ## Documentation Index
> Fetch the complete documentation index at: https://sandbox.it-centrex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Démarrage rapide

> Initialisez le SDK Flutter GimPay et suivez un parcours d'intégration type.

## Initialisation

À faire **une seule fois**, au démarrage de l'application.

**Production - tokenProvider (recommandé)**

Votre application **n'embarque aucun credential GimPay**. Votre backend détient le `clientId`/`clientSecret`, obtient le token auprès de GimPay et le relaie à l'app :

```dart theme={null}
import 'package:gimpay_sdk/gimpay_sdk.dart';

void main() {
  Gimpay.initializeWithTokenProvider(
    baseUrl: 'https://<environnement>.gimpayapp.com',
    environment: GimpayEnvironment.production, // ou .sandbox (défaut : production)
    tokenProvider: () async {
      // Appelez VOTRE backend (utilisateur déjà authentifié chez vous).
      final r = await monApiBackend.post('/gimpay/token');
      return r.accessToken;
    },
  );
  runApp(const MyApp());
}
```

Le `tokenProvider` est appelé au premier appel API puis à chaque expiration du token (réponse `401`), avec garantie **single-flight** : même si plusieurs requêtes expirent en même temps, votre backend ne reçoit qu'un seul appel.

> [!NOTE]
>
> `environment` (`GimpayEnvironment.production` par défaut, ou `.sandbox`) **isole le token stocké** : en `sandbox`, il est persisté sous une clé dédiée du stockage sécurisé, distincte de celle de `production`. Une même application installée en flavor sandbox et en flavor production sur le même appareil ne peut donc jamais relire le token d'un environnement et l'envoyer sur l'autre. Alignez-le sur la `baseUrl`.

**Contrat à implémenter côté backend partenaire** (une seule route) :

**1. Authentifiez l'utilisateur**

Utilisez votre mécanisme habituel.

**2. Appelez GIMgar Sud**

`POST {baseUrl}/api/v1/auth/token` en `application/x-www-form-urlencoded` avec `grant_type=client_credentials`, `client_id`, `client_secret` (stockés côté serveur : variables d'environnement, vault...).

**3. Renvoyez le token à l'app**

Renvoyez l'`access_token` à l'app (TLS obligatoire). Ne le mettez pas en cache plus longtemps qu'`expires_in`.

**Sandbox / prototypage - credentials embarqués**

```dart theme={null}
Gimpay.initialize(
  baseUrl: 'https://<sandbox>.gimpayapp.com',
  clientId: '<client-id-sandbox>',
  clientSecret: '<client-secret-sandbox>',
  environment: GimpayEnvironment.sandbox, // défaut : production
  enableLogs: true, // logs internes ; toujours désactivés en release
);
```

> [!WARNING]
>
> Tout ce qui est compilé dans un APK/IPA est extractible par rétro-ingénierie. Ce mode est réservé au sandbox ou à des credentials dédiés, supervisés et révocables. Ne publiez **jamais** une application grand public avec des credentials de production embarqués.

## Parcours type

Toutes les fonctionnalités passent par la façade statique `Gimpay`. Chaque méthode est documentée (dartdoc) avec son endpoint.

```dart theme={null}
// Référentiels
final pays = await Gimpay.getCountries();
final types = await Gimpay.getWalletTypes();
final contributeurs = await Gimpay.getContributors(
  typeInstrument: TypeInstrument.MOBILE_WALLET,
  codeIso: 'CIV',
);

// Enrôler un client avec son premier instrument
final enrolement = await Gimpay.enrollClient(
  client: Client(/* données KYC */),
  wallet: const Wallet(
    typeInstrument: TypeInstrument.MOBILE_WALLET,
    msisdn: '0140919386',
  ),
  terminal: const Terminal(marque: '…', modele: '…', numeroSerie: '…'),
  refContributeurDemandeur: '<ref>',
  refContributeurEmetteur: '<ref>',
);
final refUsager = enrolement.refUsagerGIMpay!;

// Instruments et solde
final wallets = await Gimpay.getUserWallets(refUsager);
final solde = await Gimpay.getBalance(wallets.first.reference!);

// Frais puis opération (avec OTP si requis par le service)
final frais = await Gimpay.calculateFees(
    refService: '<ref-service>', amount: 15000);

// Générer un OTP de débit si besoin
await Gimpay.generateDebitOtp('<ref-instrument>');

// ... l'utilisateur saisit l'OTP reçu ...
final operation = await Gimpay.executeOperation(
  libelle: 'Paiement',
  montant: 15000,
  refInstrumentPaiementInitiateur: '<ref-instrument>',
  typeOperation: TypeOperation.P2P,
  refService: '<ref-service>',
  refContributeurBeneficiaire: '<ref-contributeur>',
  authData: '<code-otp>',
);

switch (operation.statutOperation) {
  case StatutOperation.SUCCES: /* … */
  case StatutOperation.ECHOUE: /* operation.raisonEchec */
  default: /* statut intermédiaire ou inconnu */
}
```

Autres fonctionnalités via la façade `Gimpay` : cycle de vie des instruments (verrouillage/déverrouillage/désenrôlement, mouvements, opérations), bénéficiaires et mini-places de marché favorites, vérifications d'existence et d'autorisation, documents d'identité, consentements et demandes d'achat. Voir la [couverture complète des APIs](https://sandbox.it-centrex.com/sdks/api-coverage.md).

## Étapes suivantes

> **[Gestion des erreurs](https://sandbox.it-centrex.com/sdks/error-handling.md)**
>
> Exceptions typées et bonnes pratiques.

> **[Couverture des APIs](https://sandbox.it-centrex.com/sdks/api-coverage.md)**
>
> La liste complète des endpoints et énumérations disponibles.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.