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

# Déclencher un événement de test

> Sandbox uniquement. Crée un événement du type demandé avec des données d'exemple au format de l'objet réel, puis l'envoie à vos endpoints sandbox comme un vrai. Rien d'autre n'est créé : les identifiants ne renvoient à aucun objet, et `data.metadata.test_helper` vaut `true` quand l'objet a des métadonnées. Avec une clé live, la réponse est `403`. C'est ce qu'utilise `mercypay trigger`.



## OpenAPI

````yaml POST /api/v1/test_helpers/events
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.
  - name: Journal des requêtes
    description: >-
      Les appels faits avec vos clés, pour suivre une intégration depuis le
      terminal.
  - name: Sites autorisés
    description: Les sites sur lesquels le paiement intégré peut s'afficher.
paths:
  /api/v1/test_helpers/events:
    post:
      tags:
        - Événements
      summary: Déclencher un événement de test
      description: >-
        Sandbox uniquement. Crée un événement du type demandé avec des données
        d'exemple au format de l'objet réel, puis l'envoie à vos endpoints
        sandbox comme un vrai. Rien d'autre n'est créé : les identifiants ne
        renvoient à aucun objet, et `data.metadata.test_helper` vaut `true`
        quand l'objet a des métadonnées. Avec une clé live, la réponse est
        `403`. C'est ce qu'utilise `mercypay trigger`.
      operationId: createTestEvent
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - payment.succeeded
                    - payment.failed
                    - payment.refunded
                    - payment.disputed
                    - payment.dispute_closed
                    - refund.succeeded
                    - refund.failed
                    - refund.canceled
                    - payout.paid
                    - payout.failed
                    - payout.canceled
                    - subscription.created
                    - subscription.updated
                    - subscription.past_due
                    - subscription.unpaid
                    - subscription.paused
                    - subscription.resumed
                    - subscription.canceled
                    - invoice.created
                    - invoice.upcoming
                    - invoice.paid
                    - invoice.canceled
                    - invoice.payment_failed
                    - checkout_session.completed
                    - provider_status.changed
                    - account.updated
                  description: Le type d'événement à déclencher.
            example:
              type: payment.succeeded
      responses:
        '201':
          description: L'événement créé
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Event'
              example:
                data:
                  id: evt_01JC9A2B3C4D5E6F7G8H9J0K1M
                  object: event
                  livemode: false
                  created: '2026-11-08T10:42:17+00:00'
                  type: payment.succeeded
                  data:
                    id: pay_5e0c8a7b3d1f4a2e9c648b7f0d2e1a93
                    object: payment
                    livemode: false
                    created: '2026-10-04T10:20:00+00:00'
                    checkout_session: null
                    amount: 1000
                    fee_amount: 50
                    net_amount: 950
                    currency: XAF
                    payment_method: mobile_money
                    mobile_money_country: CMR
                    mobile_money_provider: MTN_MOMO_CMR
                    status: succeeded
                    failure_code: null
                    failure_reason: null
                    metadata:
                      test_helper: true
                    next_action: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '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:
    Event:
      type: object
      properties:
        id:
          type: string
          description: Identifiant (`evt_…`), le même que dans le webhook
        object:
          type: string
          const: event
        livemode:
          type: boolean
        created:
          type: string
          format: date-time
        type:
          type: string
          enum:
            - payment.succeeded
            - payment.failed
            - payment.refunded
            - payment.disputed
            - payment.dispute_closed
            - refund.succeeded
            - refund.failed
            - refund.canceled
            - payout.paid
            - payout.failed
            - payout.canceled
            - subscription.created
            - subscription.updated
            - subscription.past_due
            - subscription.unpaid
            - subscription.paused
            - subscription.resumed
            - subscription.canceled
            - invoice.created
            - invoice.upcoming
            - invoice.paid
            - invoice.canceled
            - invoice.payment_failed
            - checkout_session.completed
            - provider_status.changed
            - account.updated
          description: Type de l'événement. Voir la liste commentée dans Événements.
        data:
          type: object
          description: L'objet concerné, tel qu'envoyé dans le webhook
    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
    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.