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

# Rembourser un paiement

> Rend tout le paiement au client.



## OpenAPI

````yaml POST /api/v1/payments/{id}/refunds
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/payments/{id}/refunds:
    post:
      tags:
        - Remboursements
      summary: Rembourser un paiement
      description: >-
        Rend tout ou partie du paiement au client, jusqu'à 90 jours après
        celui-ci. Sans `amount`, tout ce qui reste à rendre. Plusieurs
        remboursements partiels peuvent se suivre, un à la fois. Votre solde est
        débité du montant et de frais de remboursement (1 % du montant rendu, au
        moins 100 FCFA). Un paiement par carte se rembourse une fois ses fonds
        disponibles. Erreurs : `insufficient_balance` si le solde disponible,
        retraits réservés déduits, ne couvre pas le total ; `refund_not_allowed`
        si le paiement ne peut pas être remboursé ou si `amount` dépasse ce qui
        reste ; `409 conflict` s'il est entièrement remboursé ou si un
        remboursement est en cours.
      operationId: createRefund
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Identifiant du paiement (`pay_…`)
        - $ref: '#/components/parameters/IdempotencyKeyRequired'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                  minimum: 1
                  description: >-
                    Montant à rendre, en unités mineures de la devise du
                    paiement. Absent : tout ce qui reste à rendre.
                reason:
                  type: string
                  maxLength: 500
                  description: Motif, gardé avec le remboursement.
      responses:
        '201':
          description: Le remboursement créé
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Refund'
              example:
                data:
                  id: re_5b2c9e4a1f7d4c3e8a6b0d2f9e1c7a35
                  object: refund
                  livemode: false
                  created: '2026-11-13T09:12:00+00:00'
                  payment: pay_0b76919140c74c4c99d52f5c1734b743
                  amount: 10000
                  fee_amount: 100
                  currency: XAF
                  status: processing
                  status_detail: null
                  origin: api
                  reason: Commande annulée
                  failure_code: null
                  failure_reason: null
                  succeeded_at: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    IdempotencyKeyRequired:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        maxLength: 255
      description: >-
        Obligatoire ici. 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:
    Refund:
      type: object
      description: Un paiement rendu au client, en entier.
      properties:
        id:
          type: string
          description: Identifiant du remboursement (`re_…`)
        object:
          type: string
          const: refund
        livemode:
          type: boolean
        created:
          type: string
          format: date-time
        payment:
          type: string
          description: Le paiement remboursé (`pay_…`)
        amount:
          type: integer
          description: >-
            Montant rendu au client, en unités mineures de la devise du paiement
            : tout ce qu'il a payé.
        fee_amount:
          type: integer
          description: Frais de remboursement débités de votre solde, en plus du montant.
        currency:
          type: string
        status:
          type: string
          enum:
            - pending
            - processing
            - succeeded
            - failed
            - canceled
          description: >-
            `pending` : envoyé, réponse attendue. `processing` : en route vers
            le client. `succeeded` : arrivé. `failed` : non envoyé, montant et
            frais revenus sur votre solde. `canceled` : annulé pendant qu'il
            attendait l'opérateur.
        status_detail:
          type:
            - string
            - 'null'
          enum:
            - delayed
            - null
          description: >-
            `delayed` : l'opérateur est indisponible et le remboursement attend
            son retour, vous pouvez l'annuler.
        origin:
          type: string
          enum:
            - dashboard
            - api
            - admin
        reason:
          type:
            - string
            - 'null'
          description: Motif donné à la demande.
        failure_code:
          type:
            - string
            - 'null'
        failure_reason:
          type:
            - string
            - 'null'
        succeeded_at:
          type:
            - string
            - 'null'
          format: date-time
    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
    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.