Consulter Cash-In par ID

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

Endpoint

GET /api/external/transactions/:id

Headers

Header	Type	Obligatoire	Description
Authorization	String	Oui	ApiKey {client_id}:{client_secret}
X-Key-Case	String	Non	Définissez à camelCase pour recevoir les champs de la réponse en camelCase (par défaut snake_case)

Path Parameters

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

Exemple

curl -X GET https://api.owem.com.br/api/external/transactions/7popu57v6us7p6pcicgq12345 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

Réponse de succès (200)

{
  "worked": true,
  "data": {
    "id": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d",
    "transaction_id": "7popu57v6us7p6pcicgq12345",
    "end_to_end_id": "E37839059202603071530000001",
    "external_id": "order-9876",
    "type": "pix",
    "status": "settled",
    "amount": 300000,
    "fee_amount": 0,
    "net_amount": 300000,
    "description": "Commande #1234",
    "direction": "inbound",
    "counterparty_name": "Maria Santos",
    "payer_document": "12345678901",
    "recipient_document": "37839059000188",
    "recipient_key": "contato@empresa.com.br",
    "payer_ispb": "60701190",
    "payer_bank_name": "ITAU UNIBANCO S.A.",
    "created_at": "2026-03-07T15:30:00Z",
    "completed_at": "2026-03-07T15:30:02Z"
  }
}

Champ	Type	Description
worked	Boolean	true indique le succès de l'opération
data.id	String	ID interne de la transaction. Pour les transactions liquidées (shape standard ci-dessus), le format est hex lowercase de 32 caractères sans tirets (ex. : a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d). Dans d'autres shapes (QR pas encore lié, échecs), le champ peut ne pas être présent ou peut avoir un autre format (UUID avec tirets quand dérivé directement de qrcodes.id)
data.transaction_id	String	Identifiant public de la transaction. Pour PIX IN via ce pipeline, prend le format PIXIN + E2E (ex. : PIXINE37839059202603071530000001) -- le préfixe est toujours PIXIN suivi de l'E2E lui-même (qui commence par E). Utilisez comme identifiant opaque ; n'essayez pas d'extraire l'E2E via string-split sans précaution, car la concaténation n'a pas de séparateur
data.end_to_end_id	String	ID bout-en-bout du BACEN (E2E, format ^E\d{8}[a-zA-Z0-9]{22,26}$)
data.external_id	String | null	Identifiant de votre système. null s'il n'a pas été renseigné à la création
data.type	String	pix pour les transactions liquidées via le pipeline normal. pix_qrcode quand le id consulté ne résout que dans qrcodes (QR encore pending/expired/cancelled, OU QR déjà payé mais pas encore lié à la ligne finale dans transactions -- courte fenêtre post-settlement). pix_return dans les remboursements reçus (voir Remboursements PIX)
data.status	String	Status actuel (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	Valeur des frais en unités de base
data.net_amount	Integer	Valeur nette en unités de base (pour PIX IN, normalement amount - fee_amount)
data.description	String | null	Description de la transaction
data.direction	String	inbound pour les réceptions, outbound pour les envois
data.counterparty_name	String | null	Pour inbound, nom du payeur ; pour outbound, nom du bénéficiaire
data.payer_document	String | null	CPF/CNPJ du payeur. Présent dans les réceptions quand la banque émettrice le transmet
data.recipient_document	String | null	CPF/CNPJ du bénéficiaire
data.recipient_key	String | null	Clé PIX utilisée dans la réception (evp/email/phone/cpf/cnpj)
data.payer_ispb	String | null	ISPB à 8 chiffres de la banque payeuse
data.payer_bank_name	String | null	Nom de la banque payeuse (résolu à partir de l'ISPB)
data.created_at	String	Date de création (ISO 8601 en UTC)
data.completed_at	String | null	Date de conclusion (ISO 8601 en UTC), null si encore en attente

L'endpoint répond aussi aux envois

Bien que ce document soit centré sur les réceptions, GET /api/external/transactions/:id est le même endpoint pour PIX IN et PIX OUT. Quand le id résout vers un envoi en traitement ou une défaillance, la réponse a le format décrit dans Consulter Cash-Out par ID (status: processing / status: failed avec reason_code/reason_description).

Status possibles

Valeurs possibles retournées dans le champ status :

Status	Origine	Description
settled	transactions	État final de succès. Paiement reçu et crédité sur le compte. Même valeur que le webhook pix.charge.paid avec status: "paid".
settled	qrcodes (fallback)	Émis aussi quand le QR a paid_at mais la ligne finale dans transactions n'a pas encore été persistée -- courte fenêtre entre Phase 2 ACCC du BACEN et la persistance locale. Dans ce cas type: "pix_qrcode" et certains champs (end_to_end_id, counterparty_name, payer_*) peuvent arriver populés seulement partiellement
pending	qrcodes	QR Code généré, en attente de paiement
expired	qrcodes	QR Code expiré (TTL configurable par compte, par défaut 1h). Également appliqué automatiquement aux QR dont expires_at est passé mais qui n'ont pas encore été traités par le worker
cancelled	qrcodes	QR Code annulé manuellement par le merchant (via portail) ou lors d'opérations administratives (ex. : migration en masse statique→dynamique d'avril/2026)
failed	failed_transactions	Tentative de crédit rejetée (ex. : limite dépassée, compte bloqué, duplicité, rejet BACEN). Le champ reason_code indique le motif structuré.

Quand failed est émis

Bien que moins fréquent qu'en cash-out, les réceptions peuvent échouer dans des scénarios spécifiques : rejet BACEN post-ACSP (ex. : AC03, AM02, DUPL), limite opérationnelle dépassée, compte destinataire bloqué ou inexistant. Dans ces cas, l'enregistrement apparaît dans failed_transactions avec direction = "inbound" et l'endpoint retourne le format additionnel suivant (champs exclusifs du chemin failed) :

{
  "worked": true,
  "data": {
    "status": "failed",
    "transaction_id": "PIXINE37839059202603071530000001",
    "end_to_end_id": "E37839059202603071530000001",
    "amount": 300000,
    "fee_amount": 0,
    "external_id": "order-9876",
    "type": "pix",
    "direction": "inbound",
    "payment_status": "failed",
    "failure_reason": "rejected: AC03",
    "reason_code": "AC03",
    "reason_description": "Invalid creditor account number",
    "started_at": "2026-03-07T15:30:00Z",
    "failed_at": "2026-03-07T15:30:02Z",
    "recipient": {
      "name": "Empresa Exemplo LTDA",
      "key": "contato@empresa.com.br"
    }
  }
}

Quand vous consultez par le tx_id du QR et que le QR n'a pas encore été payé, l'endpoint retourne pending/expired/cancelled (dérivé de qrcodes, sans ligne dans transactions). Dans ce cas le payload est réduit : id, transaction_id (= tx_id), amount, status, description, recipient_key (clé PIX du QR), type: "pix_qrcode", direction: "credit", created_at (quand le QR a été généré) et completed_at (quand payé, ou null). Le champ counterparty_name est null dans ce shape (il n'est renseigné que lorsqu'il y a une ligne réelle dans transactions).

Note sur l'annulation en masse : lors de la migration de QRs statiques vers dynamiques en avril/2026, un lot de QRs statiques avec valeur fixe actifs a été annulé administrativement (status cancelled). Les consultations retournent ce status normalement ; aucun traitement spécial n'est nécessaire.

Réponse d'erreur (404)

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

Réponse d'erreur (401)

{
  "error": {
    "status": 401,
    "message": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}

Polling vs Webhook

Pour suivre le status d'une facturation, préférez utiliser les Webhooks plutôt que le polling. Si vous devez consulter, utilisez des intervalles d'au moins 5 secondes.