> ## 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 les soldes

> Vos soldes dans l'environnement de la clé, par canal, pays et opérateur. Cette liste n'est pas paginée.

Une clé sandbox ne voit que les soldes sandbox, et une clé live que les soldes live.

Un encaissement mobile money crédite `available_balance` tout de suite. Un encaissement carte crédite d'abord `pending_balance`, qui passe en disponible en général sous 5 jours. Voir [Soldes](https://docs.mercy-pay.com/payouts/balances.md).


## OpenAPI

````yaml GET /api/v1/wallets
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/wallets:
    get:
      tags:
        - Soldes
      summary: Lire les soldes
      description: >-
        Vos soldes dans l'environnement de la clé, par canal, pays et opérateur.
        Cette liste n'est pas paginée.
      operationId: listWallets
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/StartingAfter'
        - $ref: '#/components/parameters/EndingBefore'
        - $ref: '#/components/parameters/CreatedGte'
        - $ref: '#/components/parameters/CreatedLte'
      responses:
        '200':
          description: Les soldes
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    const: list
                  url:
                    type: string
                  has_more:
                    type: boolean
                  next_cursor:
                    type:
                      - string
                      - 'null'
                    description: À passer en `starting_after` pour la page suivante
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Wallet'
              example:
                object: list
                url: /api/v1/wallets
                has_more: false
                next_cursor: null
                data:
                  - 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
                  - id: wal_7c4e9b1d2a8f4d3e9b605e1a3c8d2f97
                    object: wallet
                    livemode: false
                    created: '2026-10-02T14:05:00+00:00'
                    channel: card
                    country: null
                    provider: null
                    currency: USD
                    available_balance: 0
                    pending_balance: 4650
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      description: Nombre d'objets. Voir [Pagination](/developers/pagination)
    StartingAfter:
      name: starting_after
      in: query
      schema:
        type: string
      description: Le `next_cursor` de la page précédente
    EndingBefore:
      name: ending_before
      in: query
      schema:
        type: string
      description: Un id, pour la page qui le précède
    CreatedGte:
      name: created[gte]
      in: query
      schema:
        type: string
      description: Créés à partir de cette date (ISO 8601 ou horodatage Unix)
    CreatedLte:
      name: created[lte]
      in: query
      schema:
        type: string
      description: Créés jusqu'à cette date
  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
    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.