> ## 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.

# Lire le compte

> Le marchand de la clé, l'environnement de cette clé, vos frais (taux par canal, frais fixe carte, qui les paie), les pays mobile money ouverts, vos limites et vos soldes. Lisez-le plutôt que de recopier ces valeurs dans votre configuration.

> [!TIP]
>
> Essayez avec une clé **sandbox** (`mp_sandbox_…`) : aucun argent réel ne bouge. Voir [Test et production](https://docs.mercy-pay.com/start/environments.md).

`key_prefix` ne permet jamais de reconstituer la clé. Il sert seulement à la reconnaître dans votre tableau de bord.

Le bloc `fees` donne vos taux réels, négociés ou non, et qui paie les frais. `mobile_money` liste les pays et opérateurs ouverts. Lisez ces valeurs plutôt que de les recopier dans votre configuration : elles changent quand votre contrat ou notre couverture évoluent.


## OpenAPI

````yaml GET /api/v1/account
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/account:
    get:
      tags:
        - Compte
      summary: Lire le compte
      description: >-
        Le marchand de la clé, l'environnement de cette clé, vos frais (taux par
        canal, frais fixe carte, qui les paie), les pays mobile money ouverts,
        vos limites et vos soldes. Lisez-le plutôt que de recopier ces valeurs
        dans votre configuration.
      operationId: getAccount
      responses:
        '200':
          description: Le compte
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      merchant:
                        type: object
                        properties:
                          uuid:
                            type: string
                            format: uuid
                            description: Identifiant du marchand
                          name:
                            type: string
                            description: Nom de la boutique
                          status:
                            type: string
                            description: Statut du compte
                            enum:
                              - pending
                              - active
                              - suspended
                          kyc_status:
                            type: string
                            description: >-
                              Statut de la vérification d'identité, `approved`
                              pour encaisser en live
                            enum:
                              - not_submitted
                              - pending
                              - approved
                              - rejected
                          default_currency:
                            type: string
                            description: Devise par défaut
                      api_key:
                        type: object
                        properties:
                          environment:
                            type: string
                            description: Environnement de la clé
                            enum:
                              - sandbox
                              - live
                          key_prefix:
                            type: string
                            description: >-
                              Début de la clé, pour la reconnaître. Ne permet
                              jamais de la reconstituer.
                      fees:
                        type: object
                        properties:
                          paid_by:
                            type: string
                            enum:
                              - merchant
                              - customer
                            description: Qui paie les frais de vos paiements
                          exempt:
                            type: boolean
                            description: >-
                              `true` si vous ne payez que le coût du
                              prestataire, sans marge
                          mobile_money:
                            type: object
                            properties:
                              rate_bps:
                                type: integer
                                description: Taux en points de base (350 = 3,5 %)
                              negotiated:
                                type: boolean
                                description: '`true` si ce taux a été négocié pour vous'
                          card:
                            type: object
                            properties:
                              rate_bps:
                                type: integer
                                description: Taux en points de base (350 = 3,5 %)
                              negotiated:
                                type: boolean
                                description: '`true` si ce taux a été négocié pour vous'
                              fixed_fee:
                                type: object
                                additionalProperties:
                                  type: integer
                                description: >-
                                  Frais fixe ajouté à chaque paiement carte, en
                                  unités mineures, par devise
                          payout:
                            type: object
                            properties:
                              rate_bps:
                                type: integer
                          refund:
                            type: object
                            properties:
                              rate_bps:
                                type: integer
                              minimum:
                                type: object
                                additionalProperties:
                                  type: number
                                description: Frais minimum par devise, en unités majeures
                              window_days:
                                type: integer
                                description: Délai pour rembourser après le paiement
                      mobile_money:
                        type: array
                        description: Pays mobile money ouverts
                        items:
                          type: object
                          properties:
                            country:
                              type: string
                              description: Code pays ISO à 3 lettres
                            currency:
                              type: string
                            providers:
                              type: array
                              items:
                                type: string
                      limits:
                        type: object
                        properties:
                          monthly_volume:
                            type:
                              - object
                              - 'null'
                            description: >-
                              Plafond mensuel d'encaissement d'un compte
                              particulier, `null` pour une entreprise
                            properties:
                              amount:
                                type: integer
                              currency:
                                type: string
                          payout_max_amount:
                            type: object
                            additionalProperties:
                              type: integer
                            description: >-
                              Montant maximum d'un retrait, en unités mineures,
                              par devise
                          payout_requests_per_hour:
                            type: integer
                      wallets:
                        type: array
                        items:
                          $ref: '#/components/schemas/Wallet'
              example:
                data:
                  merchant:
                    uuid: 0b6c2f1e-6d1a-4a3e-9d0a-2f3c1b7e8a41
                    name: Boutique Ada
                    status: active
                    kyc_status: approved
                    default_currency: XAF
                  api_key:
                    environment: sandbox
                    key_prefix: mp_sandbox_9Kd2mQ7Z
                  wallets:
                    - id: wal_3f1a8c2e5b7d4e9a8c610d2f4b9a7e15
                      object: wallet
                      livemode: false
                      created: '2026-09-12T08:30:00+00:00'
                      channel: mobile_money
                      country: CMR
                      provider: MTN_MOMO_CMR
                      currency: XAF
                      available_balance: 9500
                      pending_balance: 0
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Wallet:
      type: object
      properties:
        id:
          type: string
          description: Identifiant du solde (`wal_…`)
        object:
          type: string
          const: wallet
        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
        channel:
          type: string
          description: Canal
          enum:
            - mobile_money
            - card
        country:
          type:
            - string
            - 'null'
          description: Pays, `null` pour la carte.
        provider:
          type:
            - string
            - 'null'
          description: Opérateur, `null` pour la carte.
        currency:
          type: string
          description: Devise du solde
        available_balance:
          type: integer
          description: Disponible pour un retrait, en unités mineures.
        pending_balance:
          type: integer
          description: >-
            Comptabilisé mais pas encore disponible (carte : jusqu'à ce que les
            fonds nous soient versés, en général sous 5 jours), en unités
            mineures.
    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
    Forbidden:
      description: Compte suspendu, ou clé live avant l'approbation du KYC
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: authentication_error
              code: live_mode_requires_kyc
              message: Le mode live demande un KYC approuvé.
              param: null
              doc_url: >-
                https://docs.mercy-pay.com/developers/errors#live_mode_requires_kyc
              request_id: req_01jc8x4m2v7t9qk3n5w6y8z0ab
    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.