> ## 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.
# Vérifier l'existence d'un instrument de paiement
> Déterminer si un instrument de paiement est déjà enrôlé dans GIMpay, et déclencher l'envoi d'un OTP si ce n'est pas le cas.
C'est le **point de départ de tout enrôlement**. Cet appel vérifie si un instrument de paiement est déjà connu de GIMpay et, s'il ne l'est pas, déclenche l'envoi d'un OTP au numéro rattaché au compte amorçant ainsi le parcours d'enrôlement.
## Interpréter la réponse
La logique de cet endpoint est inversée par rapport à ce que son nom suggère :
| Réponse | Signification | Suite du parcours |
| ----------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `200` avec `body: true` | L'instrument **n'existe pas encore** dans GIMpay. Un OTP vient d'être envoyé au numéro rattaché. | [Validez l'OTP](/endpoints/otp/verify), puis [enrôlez l'usager](/endpoints/users/enroll). |
| `400` | L'instrument de paiement fourni **existe déjà**. | Inutile de l'enrôler à nouveau. |
Le `400` n'est pas ici une erreur de votre requête au sens habituel : c'est le résultat métier « instrument déjà enrôlé ». Ne le traitez pas comme une donnée malformée dans votre gestion d'erreurs, sous peine d'afficher un message trompeur à l'usager.
## Les quatre champs sont obligatoires
Contrairement à beaucoup d'endpoints où certains champs sont facultatifs, les quatre sont ici tous exigés :
| Champ | Rôle |
| ------------------------- | ------------------------------------------------------------------------------- |
| `identifiantCompte` | Identifiant du compte chez le contributeur émetteur (code client, MSISDN, RIB…) |
| `indicatif` | Indicatif international **sans** le symbole `+` |
| `numero` | Numéro de téléphone lié au compte |
| `refContributeurEmetteur` | Référence du contributeur détenteur de l'instrument |
Notez soigneusement `indicatif` et `numero` : [la vérification de l'OTP](/endpoints/otp/verify) exigera exactement les mêmes valeurs.
## Réponses
Le corps utile est un booléen dans `body`, à l'intérieur de l'enveloppe commune `{ message, status, body, timestamp }`. Un `404` indique que le contributeur renseigné est introuvable — vérifiez `refContributeurEmetteur` via `GET /contributors`.
Voir la [référence des codes d'erreur](/getting-started/errors).
## Et ensuite ?
Validez le code reçu par l'usager auprès du contributeur émetteur.
Créez l'usager et rattachez son premier instrument de paiement.
## OpenAPI
````yaml openapi.json POST /api/v1/check-existence
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/check-existence:
post:
tags:
- Wallets
summary: Vérifier l'existence d'un instrument de paiement
operationId: checkExistence
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CheckExistenceRequest'
responses:
'200':
$ref: '#/components/responses/BooleanBody'
'400':
$ref: '#/components/responses/Error400'
'401':
$ref: '#/components/responses/Error401'
'500':
$ref: '#/components/responses/Error500'
components:
schemas:
CheckExistenceRequest:
type: object
required:
- refContributeurEmetteur
- identifiantCompte
- numero
- indicatif
properties:
refContributeurEmetteur:
type: string
description: >-
La référence du contributeur émetteur de l'instrument de paiement à
enrôler
identifiantCompte:
type: string
description: >
MSISDN (mobile wallet), RIB (compte bancaire), code client (carte
prépayée) ou 4 derniers chiffres du PAN (carte bancaire).
numero:
type: string
description: Numéro local du téléphone.
indicatif:
type: string
example: '225'
description: Indicatif international pays, sans le symbole +.
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.
ErrorEnvelope:
allOf:
- $ref: '#/components/schemas/ApiEnvelope'
- type: object
properties:
body:
nullable: true
responses:
BooleanBody:
description: Succès. Le `body` de l'enveloppe est un booléen.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiEnvelope'
- type: object
properties:
body:
type: boolean
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`.
````