> For the complete documentation index, see [llms.txt](https://qosic.gitbook.io/qospay/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://qosic.gitbook.io/qospay/merchant-api/payments/transaction-status.md).

# transaction status

La consultation du statut est limitée au marchand authentifié : un marchand ne peut pas récupérer la transaction d’un autre marchand, même s’il connaît sa référence.

```http
GET /api/v1/transactions/status/FT-20260810-000001 HTTP/1.1
Host: api.example.com
Authorization: Bearer <access-token>
Accept: application/json
```

Encodez `transRef` dans l’URL lorsqu’il contient des caractères qui ne sont pas sûrs dans une URL.

```bash
curl "https://api.example.com/api/v1/transactions/status/FT-20260810-000001" \
  --header "Authorization: Bearer ${QOS_ACCESS_TOKEN}" \
  --header "Accept: application/json"
```

### Consultation réussie — HTTP 200

```json
{
  "data": {
    "status": "SUCCESSFUL",
    "responseCode": "00",
    "transRef": "FT-20260810-000001",
    "providerReference": "PRV-93284723",
    "requestedAmount": "5000.00",
    "amountPaid": "5000.00",
    "fee": "50.0000",
    "residualAmount": null,
    "providerHttpStatusCode": null
  },
  "message": "Success",
  "success": true,
  "responseCode": "00"
}
```

| Champ de données         | Signification                                                                                 |
| ------------------------ | --------------------------------------------------------------------------------------------- |
| `status`                 | État actuel de la transaction. Voir le tableau ci-dessous.                                    |
| `responseCode`           | Code de réponse de la transaction/provider enregistré, et non le code de l’enveloppe externe. |
| `transRef`               | Référence marchand fournie lors de l’initiation.                                              |
| `providerReference`      | Référence du provider lorsqu’elle est disponible.                                             |
| `requestedAmount`        | Montant de base soumis par le marchand.                                                       |
| `amountPaid`             | Montant envoyé en aval après application des règles de portage des frais.                     |
| `fee`                    | Frais calculés pour le produit.                                                               |
| `residualAmount`         | Effet net sur le wallet de collecte lorsqu’il est renseigné.                                  |
| `providerHttpStatusCode` | Champ réservé au statut HTTP du provider ; il peut être `null`.                               |

### Statuts de transaction

| Statut                     | Final ?                             | Action du marchand                                                                                                                                        |
| -------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PENDING`                  | Non                                 | Interrogez à nouveau le statut avec un backoff borné. Ne soumettez pas de nouveau le paiement.                                                            |
| `SUCCESSFUL`               | Oui                                 | Exécutez la commande et rapprochez l’entrée correspondante dans le wallet/rapport.                                                                        |
| `FAILED`                   | Oui                                 | N’exécutez pas la commande. Pour les opérations de débit, vérifiez l’annulation dans l’historique du wallet avant de créer une nouvelle tentative métier. |
| `REVERSAL_REVIEW_REQUIRED` | Aucune décision marchand n’est sûre | Arrêtez les nouvelles tentatives et l’exécution. Continuez les vérifications de statut et utilisez le support marchand si la situation reste non résolue. |
| Tout autre statut provider | À traiter comme non final           | Conservez la valeur exacte et continuez le polling. Ne déduisez pas une réussite à partir d’un HTTP 200.                                                  |

### Référence inconnue — HTTP 400

```json
{
  "data": null,
  "message": "Payment reference does not exist",
  "success": false,
  "responseCode": "400"
}
```

Vérifiez que la référence est exacte et qu’elle appartient bien à l’environnement marchand actif. Une transaction de test n’est plus visible dans les rapports de wallet limités à l’environnement après le passage du marchand en production, même si la recherche de transaction elle-même reste limitée au marchand.