> ## Documentation Index > Fetch the complete documentation index at: https://docs.mercy-pay.com/llms.txt > Use this file to discover all available pages before exploring further. # Créer un client > Crée un client avant son premier abonnement. Un e-mail déjà utilisé renvoie `409` avec l'id du client existant. ## OpenAPI ````yaml POST /api/v1/customers openapi: 3.1.0 info: title: API Mercy Pay version: 1.0.0 description: >- Encaissez par mobile money et par carte, facturez en récurrent et versez vos fonds. Les montants sont des entiers en unités mineures. Chaque réponse porte un en-tête `Request-Id`. servers: - url: https://mercy-pay.com description: >- Production. La clé choisit l'environnement : `mp_sandbox_…` ou `mp_live_…`. security: - bearerAuth: [] tags: - name: Compte - name: Sessions de paiement - name: Paiements - name: Remboursements description: Rendre un paiement au client, en entier. - name: Liens de paiement - name: Plans - name: Abonnements - name: Clients - name: Factures - name: Espace client - name: Soldes - name: Retraits - name: État des opérateurs - name: Événements description: Tout ce qui s'est passé sur le compte, envoyé ou non à un endpoint. - name: Endpoints de webhook description: Les URL de votre serveur qui reçoivent les événements. paths: /api/v1/customers: post: tags: - Clients summary: Créer un client description: >- Crée un client avant son premier abonnement. Un e-mail déjà utilisé renvoie `409` avec l'id du client existant. operationId: createCustomer parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object required: - email properties: email: type: string format: email description: E-mail, unique par environnement name: type: - string - 'null' description: Nom metadata: type: object additionalProperties: true description: >- Vos données libres (jusqu'à 50 clés, valeurs de 500 caractères au plus), renvoyées dans les réponses et les webhooks. Par exemple votre numéro de commande. example: email: fatou.diallo@example.com name: Fatou Diallo metadata: crm_id: CLI-0457 responses: '201': description: Le client créé content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Customer' example: data: id: cus_2a7e4c9b1d3f4a6e8b0c5d7f9e1a3b5c object: customer livemode: false created: '2026-11-08T09:12:00+00:00' email: fatou.diallo@example.com name: Fatou Diallo metadata: crm_id: CLI-0457 default_payment_method: null subscriptions_count: 0 '401': $ref: '#/components/responses/Unauthorized' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: >- Une clé unique par opération : la rejouer pendant 24 heures renvoie la même réponse sans rien créer de plus. Voir [Idempotence](/developers/idempotency). schemas: Customer: type: object properties: id: type: string description: Identifiant du client (`cus_…`) object: type: string const: customer livemode: type: boolean description: '`true` pour de l''argent réel (clé live), `false` en sandbox' created: type: - string - 'null' format: date-time description: Date de création, ISO 8601 email: type: string description: E-mail, unique par environnement name: type: - string - 'null' description: Nom metadata: type: - object - 'null' additionalProperties: true description: Vos données libres. Voir [Metadata](/developers/metadata). default_payment_method: type: - string - 'null' description: Moyen essayé en premier (`pm_…`), `null` si aucun payment_methods: type: array items: $ref: '#/components/schemas/PaymentMethod' description: >- Moyens enregistrés, du plus ancien au plus récent. Renvoyé par le détail d'un client. subscriptions_count: type: integer description: Nombre d'abonnements. Renvoyé par la liste. PaymentMethod: type: object properties: id: type: string description: Identifiant du moyen de paiement (`pm_…`) object: type: string const: payment_method livemode: type: boolean description: '`true` pour de l''argent réel (clé live), `false` en sandbox' created: type: - string - 'null' format: date-time description: Date de création, ISO 8601 type: type: string description: Type enum: - card - mobile_money label: type: string description: Libellé lisible, par exemple `Visa •• 4242` brand: type: - string - 'null' description: 'Carte : marque' last4: type: - string - 'null' description: 'Carte : 4 derniers chiffres' exp_month: type: - integer - 'null' description: 'Carte : mois d''expiration' exp_year: type: - integer - 'null' description: 'Carte : année d''expiration' country: type: - string - 'null' description: 'Mobile money : pays' provider: type: - string - 'null' description: 'Mobile money : opérateur' phone_last_digits: type: - string - 'null' description: >- Mobile money : les 2 derniers chiffres. Le numéro complet n'est jamais renvoyé. verified: type: boolean description: >- `true` dès qu'un paiement a réussi avec ce moyen. Un numéro est confirmé ainsi, sans SMS. Error: type: object properties: error: type: object properties: type: type: string enum: - authentication_error - invalid_request_error - idempotency_error - payment_error - rate_limit_error - api_error code: type: string description: Code stable, à tester dans votre code message: type: string description: Explication en français, pour un humain param: type: - string - 'null' description: Le premier champ en cause doc_url: type: string description: Explication de ce code request_id: type: string description: >- Identifiant de la requête (`req_…`), aussi dans l'en-tête `Request-Id` errors: type: object additionalProperties: type: array items: type: string description: Détail par champ refusé, sur une erreur `422` required: - error responses: Unauthorized: description: Clé absente, invalide ou révoquée content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: authentication_error code: api_key_invalid message: Clé API invalide. param: null doc_url: https://docs.mercy-pay.com/developers/errors#api_key_invalid request_id: req_01jc8x4m2v7t9qk3n5w6y8z0ab Conflict: description: Conflit avec l'état de la ressource, ou clé d'idempotence réutilisée content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: invalid_request_error code: conflict message: 'Cette ressource est utilisée : archivez-la.' param: null doc_url: https://docs.mercy-pay.com/developers/errors#conflict request_id: req_01jc8x4m2v7t9qk3n5w6y8z0ab ValidationFailed: description: Données invalides, avec le détail dans `errors` content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: invalid_request_error code: validation_failed message: Le champ amount est obligatoire. param: amount doc_url: https://docs.mercy-pay.com/developers/errors#validation_failed request_id: req_01jc8x4m2v7t9qk3n5w6y8z0ab errors: amount: - Le champ amount est obligatoire. RateLimited: description: Plus de 60 requêtes par minute avec cette clé content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: rate_limit_error code: rate_limited message: Trop de requêtes. param: null doc_url: https://docs.mercy-pay.com/developers/errors#rate_limited request_id: req_01jc8x4m2v7t9qk3n5w6y8z0ab securitySchemes: bearerAuth: type: http scheme: bearer description: >- Votre clé API. Utilisez une clé sandbox (`mp_sandbox_…`) pour essayer : aucun argent réel ne bouge. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.