Consulter Cash-Out par ID

Consultez les détails et le status d'une transaction PIX par son transaction_id.

Endpoint

GET /api/external/transactions/:id

Headers

Header	Type	Obligatoire	Description
`Authorization`	String	Oui	`ApiKey {client_id}:{client_secret}`

Path Parameters

Paramètre	Type	Obligatoire	Description
`id`	String	Oui	ID de la transaction (`transaction_id`)

Exemple

bash

curl -X GET https://api.minhakonta.com/api/external/transactions/PIXOUT20260309a1b2c3d4e5f6 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

La réponse varie selon l'état de la transaction. Cet endpoint retourne l'état le plus récent connu par Minha Konta pour l'identifiant fourni. Si l'identifiant n'est pas trouvé, il retourne 404.

Une transaction rejetée N'apparaît PAS ici par transaction_id

Certains rejets asynchrones peuvent ne pas être localisés par transaction_id immédiatement. Utilisez les endpoints alternatifs :

GET /transactions/e2e/:e2e_id pour consulter par End-to-End ID
GET /transactions/ref/:external_id pour consulter par votre identifiant externe
Webhook pix.payout.rejected / pix.payout.failed pour notification en temps réel avec payload complet

Les rejets de validation d'entrée (400/422 immédiat) ne passent pas par ce flux parce qu'ils ont déjà retourné l'erreur synchrone au POST.

Réponse -- Transaction liquidée (200)

json

{
  "worked": true,
  "data": {
    "id": "c7f3a8b12d4e4f6a9c1b3e5f7a9b1d3e",
    "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
    "end_to_end_id": "E04838403202603091530abcdef01",
    "external_id": "order-9876",
    "type": "pix",
    "direction": "outbound",
    "status": "settled",
    "amount": 300000,
    "fee_amount": 350,
    "net_amount": 300350,
    "description": "Paiement fournisseur",
    "counterparty_name": "Joao Silva",
    "recipient_key": "12345678901",
    "created_at": "2026-03-09T15:30:00Z",
    "completed_at": "2026-03-09T15:30:02Z"
  }
}

Champ	Type	Description
`data.id`	String	ID interne de la transaction au format UUID canonique avec tirets, quand disponible
`data.transaction_id`	String	Identifiant unique de la transaction. Lisez toujours le champ retourné ; ne dérivez pas de règle depuis un préfixe
`data.end_to_end_id`	String	Identifiant End-to-End dans le SPI/BACEN
`data.external_id`	String	Identifiant de votre système. `null` s'il n'a pas été renseigné
`data.type`	String	Type de la transaction. Valeurs courantes : `pix`, `pix_return`
`data.direction`	String	Direction du mouvement : `outbound` (cash-out), `inbound` (cash-in), `credit` ou `debit`
`data.status`	String	Status normalisé (voir tableau ci-dessous)
`data.amount`	Integer	Valeur en unités de base (÷ 10 000 pour reais). `300000` = R$ 30,00
`data.fee_amount`	Integer	Frais prélevés en unités de base
`data.net_amount`	Integer	Valeur nette en unités de base
`data.description`	String	Description renseignée à la création
`data.counterparty_name`	String	Nom de la contrepartie (payeur ou bénéficiaire)
`data.recipient_key`	String	Clé PIX du destinataire (uniquement pour les sorties)
`data.created_at`	String	Date de création (ISO 8601)
`data.completed_at`	String	Date de conclusion (ISO 8601), `null` si en attente

Réponse -- PIX OUT en cours (200)

Retourné quand la transaction est encore en cours de traitement (avant confirmation BACEN).

json

{
  "worked": true,
  "data": {
    "status": "processing",
    "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
    "end_to_end_id": "E04838403202603091530abcdef01",
    "amount": 300000,
    "fee_amount": 350,
    "net_amount": 300350,
    "external_id": "order-9876",
    "pix_key": "12345678901",
    "description": "Paiement fournisseur",
    "type": "pix",
    "direction": "outbound",
    "payment_status": "processing",
    "started_at": "2026-03-09T15:30:00Z",
    "recipient": {
      "name": "Joao Silva",
      "key": "12345678901",
      "key_type": "cpf"
    }
  }
}

Champ additionnel	Type	Description
`data.recipient`	Object	Données du destinataire résolues via DICT
`data.recipient.name`	String	Nom du titulaire de la clé
`data.recipient.key`	String	Clé PIX utilisée
`data.recipient.key_type`	String	Type de la clé (`cpf`, `cnpj`, `email`, `phone`, `evp`)
`data.started_at`	String	Date de début du traitement (ISO 8601)

Réponse -- Transaction rejetée (200)

Retournée par les endpoints /transactions/e2e/:e2e_id et GET /transactions/ref/:external_id quand le PIX a été rejeté par le SPI ou a échoué pendant le traitement.

json

{
  "worked": true,
  "data": {
    "status": "failed",
    "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
    "end_to_end_id": "E04838403202603091530abcdef01",
    "amount": 300000,
    "fee_amount": 350,
    "external_id": "order-9876",
    "type": "pix",
    "direction": "outbound",
    "payment_status": "failed",
    "failure_reason": "rejected: AB03",
    "reason_code": "AB03",
    "reason_description": "Aborted by PSP of creditor",
    "started_at": "2026-03-09T15:30:00Z",
    "failed_at": "2026-03-09T15:30:05Z",
    "recipient": {
      "name": "Joao Silva",
      "key": "12345678901"
    }
  }
}

Champ additionnel	Type	Description
`data.failure_reason`	String	Motif brut du rejet (format : `"rejected: {CODE}"` pour les codes BACEN, ou descriptions d'intégration comme `"dict_key_not_found"`, `"ambiguous key"`, `"insufficient balance"`)
`data.reason_code`	String	Code structuré extrait de `failure_reason`. Pour les rejets BACEN, suit ISO 20022 (`AC03`, `AB03`, `ED05`, `DUPL` etc.). `null` quand `failure_reason` ne contient pas de code structuré
`data.reason_description`	String	Description humaine du `reason_code`, en anglais. Exemples : `"Invalid creditor account number"` (AC03), `"Aborted by PSP of creditor"` (AB03), `"Settlement failed"` (ED05). `null` quand le code n'est pas reconnu
`data.recipient`	Object	Données du destinataire (quand disponibles). Peut être omis dans les échecs très précoces
`data.failed_at`	String	Date/heure du rejet (ISO 8601)

Structure des codes de rejet

Utilisez reason_code et reason_description pour le routage programmatique des erreurs. Gardez failure_reason uniquement pour les logs et le diagnostic. Voir le tableau complet des codes dans PIX Cash-Out par clé -- Codes d'erreur.

Réponse -- QR Code non payé (200)

Retournée quand l'ID correspond à un QR Code qui n'a pas encore été payé.

json

{
  "worked": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "transaction_id": "7popu57v6us7p6pcicgq12345",
    "end_to_end_id": null,
    "external_id": "order-9876",
    "type": "pix_qrcode",
    "status": "pending",
    "amount": 300000,
    "fee_amount": 0,
    "net_amount": 300000,
    "description": "Cobrança PIX",
    "direction": "credit",
    "counterparty_name": null,
    "recipient_key": "12345678901",
    "created_at": "2026-03-09T15:30:00Z",
    "completed_at": null
  }
}

Status QR	Description
`pending`	QR Code actif, en attente de paiement
`settled`	QR Code payé, mais la transaction finale est encore en consolidation. Ne le traitez pas comme une erreur ; refaites la consultation quelques secondes plus tard
`expired`	QR Code expiré
`cancelled`	QR Code annulé manuellement

Note : quand le QR est payé et que la transaction finale est déjà consolidée, la réponse devient le shape « Transaction liquidée » ci-dessus.

Valeurs du champ `status`

Status du GET

Le GET /transactions/:id retourne un status normalisé pour le suivi opérationnel.

Status	Signification
`processing`	PIX OUT accepté et pas encore final. Il peut attendre la confirmation BACEN ou un retraitement automatique dû à une limite DICT
`settled`	BACEN a confirmé la liquidation et le solde a déjà été mouvementé. État final de succès
`pending`	État intermédiaire rare avant conclusion
`failed`	État final d'échec. Rejeté par BACEN, expiré en retraitement automatique (`DICT_QUEUE_TIMEOUT`) ou échec opérationnel

Note de compatibilité : les rows legacy (antérieures à la consolidation du vocabulaire) peuvent présenter status: "completed" ou status: "accepted". Traitez-les comme équivalents à "settled".

Correspondance avec les webhooks

pix.payout.queued correspond à status: "processing" tant que la transaction attend un retraitement automatique
pix.payout.confirmed correspond toujours à status: "settled" dans le GET
pix.payout.failed et pix.payout.rejected correspondent toujours à status: "failed" dans le GET

Pour les QR Codes (cash-in, hors du scope PIX OUT), les valeurs possibles sont pending, settled, expired et cancelled, décrites dans la section « QR Code non payé » ci-dessus.

Réponse d'erreur -- 404

json

{
  "worked": false,
  "detail": "Transação não encontrada"
}

Consulter Cash-Out par ID ​

Endpoint ​

Headers ​

Path Parameters ​

Exemple ​

Réponse -- Transaction liquidée (200) ​

Réponse -- PIX OUT en cours (200) ​

Réponse -- Transaction rejetée (200) ​

Réponse -- QR Code non payé (200) ​

Valeurs du champ status ​

Correspondance avec les webhooks ​

Réponse d'erreur -- 404 ​

Consulter Cash-Out par ID

Endpoint

Headers

Path Parameters

Exemple

Réponse -- Transaction liquidée (200)

Réponse -- PIX OUT en cours (200)

Réponse -- Transaction rejetée (200)

Réponse -- QR Code non payé (200)

Valeurs du champ `status`

Correspondance avec les webhooks

Réponse d'erreur -- 404