> ## Documentation Index
> Fetch the complete documentation index at: https://docs.i-pay.money/llms.txt
> Use this file to discover all available pages before exploring further.

# Consulter une transaction

> Vérifiez le statut réel d'une transaction avec sa référence iMoney Encaissement ou votre transaction_id.

Utilisez cette opération pour connaître le statut réel d'une transaction, plutôt que de vous fier au statut renvoyé à la création. C'est elle (ou un [webhook](/guides/webhooks)) qui doit déclencher la livraison d'une commande, jamais la réponse de [Créer une transaction](/api-reference/transactions/creer-un-paiement).

* **Référence.** Elle accepte deux valeurs interchangeables : la référence interne renvoyée à la création, ou votre propre `transaction_id` (retrouvé sous le nom `external_reference`). Inutile de conserver les deux si vous ne gardez que `transaction_id` côté marchand.
* **Statut.** Une transaction `pending` peut encore devenir `succeeded`, `failed` ou `refunded`. Attendez un statut définitif (ou un webhook) avant de considérer la vérification terminée.
* **Référence inconnue.** Une référence qui ne correspond à aucune transaction du compte authentifié renvoie `404`, y compris si elle existe pour un autre compte ou un autre environnement (Sandbox/Live).

La liste complète des messages d'erreur communs est dans [Erreurs](/api-reference/erreurs).


## OpenAPI

````yaml openapi.yaml GET /payments/{reference}
openapi: 3.1.0
info:
  title: iPayMoney Merchant API
  version: 1.0.0
  description: >-
    Contrats marchands v1 vérifiés contre les routes, contrôleurs et services
    Rails. Les contrats partenaires et les routes v2 non opérationnelles ne font
    pas partie de cette spécification publique. Les liens de paiement doivent
    utiliser des références aléatoires privées.
servers:
  - url: https://i-pay.money/api/v1
    description: Sandbox ou Live selon les en-têtes et la clé utilisée
security: []
tags:
  - name: Payments
    description: Création et suivi des transactions marchandes
  - name: Payment links
    description: Liens de paiement hébergés
paths:
  /payments/{reference}:
    get:
      tags:
        - Payments
      summary: Consulter une transaction
      description: >-
        Accepte la référence interne iPayMoney ou la référence externe du
        marchand.
      parameters:
        - name: reference
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/TargetEnvironment'
        - $ref: '#/components/parameters/PaymentType'
      responses:
        '200':
          description: Transaction trouvée pour le compte authentifié
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentStatus'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Transaction introuvable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '406':
          $ref: '#/components/responses/NotAcceptable'
      security:
        - bearerAuth: []
components:
  parameters:
    ContentType:
      name: Content-Type
      in: header
      required: true
      description: >-
        Exigé par l'authentification de l'API, y compris sur les requêtes GET
        qui n'ont pourtant pas de corps.
      schema:
        type: string
        const: application/json
    TargetEnvironment:
      name: Ipay-Target-Environment
      in: header
      required: true
      schema:
        type: string
        enum:
          - sandbox
          - live
    PaymentType:
      name: Ipay-Payment-Type
      in: header
      required: true
      description: >-
        Méthode de paiement. `POST /payments` ne prend en charge que `mobile`
        (mobile money). Les autres moyens de paiement (carte bancaire et autres
        canaux) ne s'utilisent pas ici : ils sont disponibles via les liens de
        paiement (`POST /external_payments`). Liste complète : [moyens de
        paiement](/guides/reversement#frais-par-moyen-de-paiement).
      x-verified: >-
        Note interne de vérification (non destinée à la documentation publique).
        Décision de périmètre : seule la valeur `mobile` est documentée pour
        `POST /payments` ; les autres valeurs traitées par
        `Live::PaymentService` restent acceptées par l'API mais relèvent du
        parcours « lien de paiement ». `external_payment` est réservé à `POST
        /external_payments` (paramètre dédié de cette opération).
      schema:
        type: string
        const: mobile
        example: mobile
  schemas:
    PaymentStatus:
      type: object
      required:
        - public_reference
        - external_reference
        - reference
        - status
        - msisdn
        - amount
      properties:
        public_reference:
          type: string
        external_reference:
          type: string
        reference:
          type: string
        status:
          type: string
          enum:
            - initiated
            - pending
            - succeeded
            - failed
            - refunded
        msisdn:
          type: string
        amount:
          type: integer
        validated_at:
          type:
            - string
            - 'null'
          format: date-time
    Error:
      type: object
      properties:
        message:
          type: string
        status:
          type: string
          description: >-
            Présent uniquement sur certains échecs applicatifs, ex. paiement
            dupliqué sur `POST /payments` où `status` vaut toujours `failed`.
            Absent des autres erreurs de ce contrat (ex. 404 `Payment Not
            Found`, erreurs d'en-tête/authentification).
          x-verified: >-
            Note interne de vérification (non destinée à la documentation
            publique). Voir `Live::PaymentService#error_response`
            (app/services/live/payment_service.rb:994-1005).
          example: failed
  responses:
    BadRequest:
      description: En-tête ou paramètre invalide, détecté avant toute logique métier.
      x-verified: >-
        Note interne de vérification (non destinée à la documentation publique).
        Détecté par `ApiAuthService#authenticate`
        (app/services/api_auth_service.rb:20-26) — messages exacts vérifiés le
        2026-09-16.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingHeaderParams:
              summary: En-tête d'authentification manquant
              value:
                message: 'Bad Request: Missing params'
            notAllowedEnvironment:
              summary: Ipay-Target-Environment non autorisé
              value:
                message: 'Bad Request: Not Allowed Environment'
            notAllowedPaymentType:
              summary: Ipay-Payment-Type non autorisé
              value:
                message: 'Bad Request: Not Allowed Payment Type'
            missingAuthenticationKey:
              summary: Authorization Bearer manquant ou mal formé
              value:
                message: 'Bad Request: Missing Authentication Key'
    Unauthorized:
      description: Clé invalide
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Compte ou environnement indisponible
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotAcceptable:
      description: Content-Type différent de application/json
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Clé secrète du compte Sandbox ou Live

````