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

# Encaisser une facture

> Encaisse tout de suite sur les moyens enregistrés du client, dans l'ordre. Le résultat arrive par `invoice.paid` ou `invoice.payment_failed`.

Une carte est débitée, ou une demande part sur le téléphone du client. Répond `422` si la facture n'est pas à payer, si l'abonnement n'est pas en cours, ou si un paiement attend déjà sa confirmation.


## OpenAPI

````yaml POST /api/v1/invoices/{id}/pay
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/invoices/{id}/pay:
    post:
      tags:
        - Factures
      summary: Encaisser une facture
      description: >-
        Encaisse tout de suite sur les moyens enregistrés du client, dans
        l'ordre. Le résultat arrive par `invoice.paid` ou
        `invoice.payment_failed`.
      operationId: payInvoice
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Identifiant de la facture (`in_…`)
      responses:
        '200':
          description: La facture
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Invoice'
              example:
                data:
                  id: in_7a3d9c2e5f1b4e8ab6c40d2e9f1a3b57
                  object: invoice
                  livemode: false
                  created: '2026-11-07T10:00:00+00:00'
                  number: F2026-000019
                  subscription: sub_4f2c8a1e0b7d4c559a3e6d1f8b2c7e90
                  kind: cycle
                  amount: 5000
                  currency: XAF
                  period_start: '2026-11-07T10:00:00+00:00'
                  period_end: '2026-12-07T10:00:00+00:00'
                  due_at: '2026-11-07T10:00:00+00:00'
                  status: pending
                  attempt_count: 1
                  next_attempt_at: '2026-11-08T10:00:00+00:00'
                  failure_reason: Solde insuffisant.
                  metadata: null
                  payment: pay_e1f2a3b4c5d64e7f8a9b0c1d2e3f4a5b
                  pay_url: https://mercy-pay.com/payer/k3j9x2pq
                  paid_at: null
                  canceled_at: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Invoice:
      type: object
      properties:
        id:
          type: string
          description: Identifiant de la facture (`in_…`)
        object:
          type: string
          const: invoice
        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
        number:
          type: string
          description: Numéro lisible, par exemple `F2026-000019`
        subscription:
          type: string
          description: >-
            Abonnement (`sub_…`). Avec `expand[]=subscription`, l'abonnement
            complet
        kind:
          type: string
          description: >-
            `first` (premier paiement qui active l'abonnement), `cycle`
            (échéance) ou `proration` (différence payée pour un plan plus cher).
          enum:
            - first
            - cycle
            - proration
        amount:
          type: integer
          description: Montant en unités mineures
        currency:
          type: string
          description: Devise
        period_start:
          type: string
          description: Début de la période facturée
          format: date-time
        period_end:
          type: string
          description: Fin de la période facturée
          format: date-time
        due_at:
          type: string
          description: Échéance
          format: date-time
        status:
          type: string
          description: >-
            `failed` : toutes les tentatives ont échoué. `canceled` : abonnement
            annulé avant paiement.
          enum:
            - pending
            - paid
            - failed
            - canceled
        attempt_count:
          type: integer
          description: Tentatives d'encaissement déjà faites
        next_attempt_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Prochaine tentative automatique, `null` s'il n'y en a pas
        failure_reason:
          type:
            - string
            - 'null'
          description: Raison du dernier échec, lisible par votre client
        metadata:
          type:
            - object
            - 'null'
          additionalProperties: true
          description: Vos données libres. Voir [Metadata](/developers/metadata).
        payment:
          type:
            - string
            - 'null'
          description: >-
            Paiement qui a réglé la facture (`pay_…`), `null` sinon. Avec
            `expand[]=payment`, le paiement complet
        pay_url:
          type:
            - string
            - 'null'
          description: >-
            Mobile money : page où le client paie cette facture, tant qu'elle
            est payable
        paid_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Date de paiement
        canceled_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Date d'annulation
    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
    NotFound:
      description: Ressource inconnue, ou d'un autre marchand ou environnement
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: resource_not_found
              message: Ressource introuvable.
              param: null
              doc_url: https://docs.mercy-pay.com/developers/errors#resource_not_found
              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.