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.

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.

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

{
  "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

{
  "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.