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

# Enrôler un usager

> Enregistrer un nouvel usager GIMpay avec son identité (KYC), son premier instrument de paiement et le terminal utilisé.

C'est le **point d'entrée de tout parcours GIMpay** : cet appel crée simultanément l'usager, son premier instrument de paiement et enregistre le terminal ayant servi à l'enrôlement. Il retourne une `refUsagerGIMpay` et une `refInstrumentPaiement`, références que vous réutiliserez dans la quasi-totalité des appels suivants.

## Avant d'appeler

<Steps>
  <Step title="Vérifiez que l'instrument n'est pas déjà enrôlé">
    Appelez [`POST /api/v1/check-existence`](/api-reference/introduction). S'il retourne `true`, l'instrument est inconnu de GIMpay et un OTP a été envoyé au numéro rattaché. L'enrôlement peut se poursuivre.
  </Step>

  <Step title="Récupérez les références de contributeur">
    `refContributeurDemandeur` (vous) et `refContributeurEmetteur` (l'établissement détenteur de l'instrument) s'obtiennent via `GET /api/v1/contributors`.
  </Step>

  <Step title="Préparez les champs requis par type d'instrument">
    Le contenu de l'objet `wallet` dépend du type d'instrument enrôlé. Voir la matrice ci-dessous.
  </Step>
</Steps>

## Champs requis selon le type d'instrument

L'objet `wallet` accepte huit champs, mais seul un sous-ensemble s'applique à chaque type d'instrument. Les autres doivent être omis.

| Type d'instrument | Champs à fournir                  |
| ----------------- | --------------------------------- |
| Mobile Wallet     | `msisdn`                          |
| Carte Débit       | `pan`, `cvv`, `typeCarteBancaire` |
| Carte Prépayée    | `codeClient`, `typeCarteBancaire` |
| Compte Bancaire   | `numeroRib`, `typeCompteBancaire` |

<Danger>
  Vous ne pouvez qu'utiliser les instruments de paiement de type `CARTE PREPAYEE` pour l'instant.
  Pour voir la liste des instruments de paiement, consultez [`GET /api/v1/wallets/type`](/api-reference/wallets/collecter-les-types-dinstruments-de-paiement)
</Danger>

## Réponses

En cas de succès, le corps utile se trouve dans `body`, à l'intérieur de l'enveloppe commune `{ message, status, body, timestamp }` :

```json Structure attendue theme={null}
{
  "message": "...",
  "status": 201,
  "body": {
    "refUsagerGIMpay": "USER-00123",
    "refInstrumentPaiement": "WALLET-00456"
  },
  "timestamp": "2026-07-16T10:24:31.482Z"
}
```

Les erreurs de validation renvoient un `400` dont le champ `message` désigne précisément le champ fautif. Voir la [référence des codes d'erreur](/getting-started/errors).

## Et ensuite ?

<CardGroup cols={2}>
  <Card title="Rattacher d'autres instruments" icon="wallet" href="/api-reference/introduction">
    `POST /wallets/card`, `/bank-account` ou `/mobile-wallet` pour ajouter des instruments à cet usager.
  </Card>

  <Card title="Vérifier les droits de l'usager" icon="shield-check" href="/api-reference/introduction">
    `GET /users/{referenceUsager}/authorization` avant toute opération financière.
  </Card>

  <Card title="Exécuter une opération" icon="arrows-rotate" href="/guides/integration-guide">
    Le parcours complet, du calcul des frais à la validation OTP.
  </Card>

  <Card title="Glossaire" icon="book" href="/glossary/enumerations">
    Valeurs acceptées pour `sexe`, `situationMatrimoniale`, `typeCarteBancaire`…
  </Card>
</CardGroup>


## OpenAPI

````yaml openapi.json POST /api/v1/users
openapi: 3.0.3
info:
  title: Registre des APIs GIM Gar Sud
  version: 1.0.9-sdk0.3.0
  description: >
    APIs exposées par GIM Gar Sud pour permettre aux Contributeurs Tiers de
    Service Financier (CTSF) de consommer les services de GIMpay : enrôlement
    d'usagers et d'instruments de paiement, opérations financières, OTP,
    consentements, documents d'identité et fidélité.
  contact:
    name: Support intégrateurs GimPay
    email: support@it-centrex.com
servers:
  - url: https://egimgarsud.gimpayapp.com
    variables:
      environnement:
        default: egimgarsud
        description: Sous-domaine de l'environnement (sandbox ou production).
security:
  - bearerAuth: []
tags:
  - name: Authentification
  - name: Wallets
    description: Instruments de paiement (cartes, comptes bancaires, mobile wallets)
  - name: Opérations
  - name: OTP
  - name: Usagers
  - name: Bénéficiaires
  - name: MMP favorites
  - name: Pays
  - name: Contributeurs
  - name: Mini-places de marché
  - name: Services
  - name: Terminaux
  - name: Documents
  - name: Consentements & demandes
paths:
  /api/v1/users:
    post:
      tags:
        - Usagers
      summary: Enrôler un client (KYC + instrument + terminal)
      operationId: enrollClient
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrollClientRequest'
      responses:
        '201':
          description: Client enrôlé.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiEnvelope'
                  - type: object
                    properties:
                      body:
                        $ref: '#/components/schemas/EnrollClientResponse'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '500':
          $ref: '#/components/responses/Error500'
components:
  schemas:
    EnrollClientRequest:
      type: object
      required:
        - kyc
        - refContributeurDemandeur
        - refContributeurEmetteur
        - terminal
        - wallet
      properties:
        kyc:
          $ref: '#/components/schemas/KycRequest'
        refContributeurDemandeur:
          type: string
          description: >-
            La référence du contributeur demandeur qui demande l'enrôlement de
            l'instrument de paiement
        refContributeurEmetteur:
          type: string
          description: >-
            La référence du contributeur émetteur de l'instrument de paiement à
            enrôler
        terminal:
          $ref: '#/components/schemas/TerminalRequest'
        wallet:
          $ref: '#/components/schemas/WalletRequest'
    ApiEnvelope:
      type: object
      description: Enveloppe standard de toutes les réponses (sauf auth).
      properties:
        message:
          type: string
          description: Message technique décrivant le résultat de l'appel.
        status:
          type: integer
          description: Code de statut HTTP de la réponse.
        timestamp:
          type: string
          format: date-time
          description: Horodatage de la réponse.
    EnrollClientResponse:
      type: object
      properties:
        refUsagerGIMpay:
          type: string
          description: Référence GIMpay de l'usager
        refInstrumentPaiement:
          type: string
          description: Référence GIMpay de l'instrument de paiement enrôlé.
    KycRequest:
      type: object
      required:
        - nom
        - prenoms
        - dateNaissance
        - lieuNaissance
        - paysNaissance
        - sexe
        - profession
        - adresseEmail
        - contactMobile1
        - nationalite
        - codeIso
      properties:
        nom:
          type: string
          description: Nom de l'usager.
          minLength: 2
          maxLength: 100
        prenoms:
          type: string
          description: Prénom(s) de l'usager.
          minLength: 3
          maxLength: 150
        dateNaissance:
          type: string
          description: Format yyyy-MM-dd.
        lieuNaissance:
          type: string
          description: Lieu de naissance de l'usager.
        paysNaissance:
          type: string
          description: Pays de naissance de l'usager.
        sexe:
          type: string
          enum:
            - MASCULIN
            - FEMININ
          description: >-
            Sexe de l'usager. Valeurs rejetées hors de cette liste (confirmé par
            test d'intégration en sandbox).
        profession:
          type: string
        adressePostale:
          type: string
          description: Adresse postale du domicile de l'usager.
        adresseGeographique:
          type: string
          description: Adresse géographique du domicile de l'usager.
        adresseEmail:
          type: string
          format: email
          description: Adresse email de l'usager.
        contactMobile1:
          type: string
          description: 10 chiffres.
        contactMobile2:
          type: string
          description: Autre contact téléphonique de l'usager.
        nomDuPere:
          type: string
          description: Nom et prénom(s) du père de l'usager.
        nomDeLaMere:
          type: string
          description: Nom et prénom(s) de la mère de l'usager.
        situationMatrimoniale:
          type: string
          description: Situation matrimoniale de l'usager.
          enum:
            - CELIBATAIRE
            - MARIE
            - DIVORCE
            - VEUF
            - VEUVE
        nomPrenomConjoint:
          type: string
          description: Nom et prénom(s) du conjoint de l'usager.
        contactMobileConjoint:
          type: string
          description: Contact téléphonique du conjoint de l'usager.
        nationalite:
          type: string
          description: Nationalité de l'usager.
        typeKyc:
          type: string
        codeIso:
          type: string
          example: CIV
          description: Le code ISO de l'instrument de paiement à enrôler
    TerminalRequest:
      type: object
      required:
        - marque
        - modele
        - numeroSerie
      properties:
        marque:
          type: string
          description: La marque du terminal
        modele:
          type: string
          description: Le modèle du terminal
        numeroSerie:
          type: string
          description: Le numéro de série du terminal
        refUsager:
          type: string
          description: >
            Champ `@Hidden` du contrat, utilisé par les endpoints
            d'acceptation/rejet de consentement.
    WalletRequest:
      type: object
      description: Instrument de paiement à enrôler avec le client
      properties:
        codeClient:
          type: string
          description: Le code de la carte bancaire
        typeCarteBancaire:
          $ref: '#/components/schemas/TypeCarteBancaire'
        numeroRib:
          type: string
          description: Le numéro RIB
        msisdn:
          type: string
          description: Le MSISDN de l'instrument de paiement à enrôler
        pan:
          type: string
          description: >-
            Les 4 derniers chiffres du PAN (Primary Account Number) de la carte
            bancaire
        cvv:
          type: string
          description: Le CVV de la carte bancaire
        typeCompteBancaire:
          $ref: '#/components/schemas/TypeCompteBancaire'
        dateExpiration:
          type: string
          description: La date d'expiration de la carte bancaire
          pattern: MM/yyyy
    ErrorEnvelope:
      allOf:
        - $ref: '#/components/schemas/ApiEnvelope'
        - type: object
          properties:
            body:
              nullable: true
    TypeCarteBancaire:
      type: string
      enum:
        - DEBIT
        - CREDIT
        - PREPAYEE
    TypeCompteBancaire:
      type: string
      enum:
        - CHEQUE
        - EPARGNE
        - DAT
  responses:
    Error400:
      description: Requête invalide (champ manquant ou mal formé).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Error401:
      description: Non autorisé — jeton manquant, invalide ou expiré.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Error500:
      description: Erreur interne du serveur.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Jeton émis par `POST /api/v1/auth/token`.

````