Consulter Transaction par External ID

Consultez une transaction par son external_id, l'identifiant défini par votre système au moment de la création (cash-in ou cash-out).

Endpoint

GET /api/external/transactions/ref/:external_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
external_id	String	Oui	Identifiant externe défini à la création de la transaction

Quand l'utiliser

Cet endpoint est utile pour la conciliation entre votre système et Owem Pay. Au lieu de stocker le transaction_id d'Owem, consultez directement par l'ID de votre commande, facture ou référence interne.

Exemple

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

Shapes de réponse

La réponse varie selon l'état de la transaction. Voir ci-dessous les 4 shapes possibles.

Shape 1 -- Transaction liquidée (status: "settled")

Retournée quand la transaction a été liquidée et persistée dans la table transactions.

{
  "worked": true,
  "data": {
    "id": "c7f3a8b1-2d4e-4f6a-9c1b-3e5f7a9b1d3e",
    "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
    "end_to_end_id": "E37839059202603091530abcdef01",
    "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",
    "payer_document": null,
    "recipient_document": "12345678901",
    "payer_ispb": null,
    "payer_bank_name": null,
    "created_at": "2026-03-09T15:30:00Z",
    "completed_at": "2026-03-09T15:30:02Z"
  }
}

Champ (top-level)	Type	Description
id	String	UUID interne de la transaction
transaction_id	String	Identifiant public de la transaction
end_to_end_id	String	E2E ID du BACEN
external_id	String	Identifiant de votre système
type	String	pix, ted, internal
direction	String	inbound ou outbound
status	String	Status de la transaction (voir pix-lifecycle)
amount	Integer	Valeur en unités de base (÷ 10 000 pour reais)
fee_amount	Integer	Frais prélevés en unités de base
net_amount	Integer	Valeur nette en unités de base
description	String	Description de la transaction
counterparty_name	String	Nom de la contrepartie
recipient_key	String	Clé PIX du destinataire (uniquement outbound)
payer_document	String	CPF/CNPJ du payeur (inbound). null pour outbound
recipient_document	String	CPF/CNPJ du bénéficiaire (outbound). null pour inbound
payer_ispb	String	ISPB de l'institution payeuse (inbound). null pour outbound
payer_bank_name	String	Nom de la banque payeuse (inbound). null pour outbound
created_at	String	Date de création (ISO 8601)
completed_at	String	Date de conclusion (ISO 8601)

Shape 2 -- Transaction en traitement (status: "processing")

Retournée quand la transaction est dans outbound_requests en attente de réponse du BACEN (pas encore liquidée ni échouée).

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

Champ	Type	Description
transaction_id	String	Identifiant public (préfixe PIXOUT)
end_to_end_id	String	E2E ID du BACEN
external_id	String	Identifiant de votre système
amount	Integer	Valeur en unités de base (÷ 10 000 pour reais)
fee_amount	Integer	Frais en unités de base
net_amount	Integer	amount + fee_amount en unités de base
status	String	Toujours "processing" dans ce shape
payment_status	String	Miroir de status pour compatibilité
type	String	pix, ted, internal
direction	String	outbound (shape exclusif de PIX OUT en vol)
pix_key	String	Clé PIX du destinataire
description	String	Description renseignée dans le request
started_at	String	Instant où la requête est entrée dans la file (ISO 8601)

Shape intermédiaire

Les transactions en processing sont en vol au BACEN. Ne vous fiez pas à cet état comme final — attendez le webhook pix.payout.confirmed ou pix.payout.failed. Les opérations en quarantaine (stage=5, sans réponse du BACEN >30min) retournent également "processing" — voir pix-lifecycle.

Shape 3 -- Transaction échouée

Retournée quand la transaction est dans failed_transactions (rejetée par le BACEN ou échec interne).

{
  "worked": true,
  "data": {
    "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
    "end_to_end_id": "E37839059202603091530abcdef01",
    "external_id": "order-9876",
    "amount": 300000,
    "status": "failed",
    "type": "pix",
    "direction": "outbound",
    "reason_code": "AC03",
    "reason_description": "Invalid creditor account number",
    "recipient": {
      "name": "Joao Silva",
      "key": "12345678901"
    },
    "failed_at": "2026-03-09T15:30:02Z"
  }
}

Champ extra	Type	Description
reason_code	String	Code BACEN/provider (ex. : AC03, ED05, AM02)
reason_description	String	Description en anglais
recipient	Object	{name, key} du destinataire
failed_at	String	Date de l'échec (ISO 8601)

Shape 4 -- QR code (cash-in)

Retourné quand le external_id a été enregistré dans un QR code de facturation (payé ou non). Utilisé comme fallback quand il n'y a pas de row dans transactions ni dans outbound_requests.

{
  "worked": true,
  "data": {
    "id": "e9f3df72-031f-49bf-abc3-a9ce1d540726",
    "tx_id": "smyoka2zd5xowvqq2hea",
    "pix_key": "evp-xxxx-xxxx-xxxx",
    "amount": 100000,
    "fee_amount": 0,
    "status": "paid",
    "external_id": "order-9876",
    "description": "Commande #1234",
    "end_to_end_id": "E37839059202604101607b2fc9d8b4c6b",
    "direction": "inbound",
    "type": "pix_qrcode",
    "created_at": "2026-04-10T16:00:00Z",
    "paid_at": "2026-04-10T16:07:08Z"
  }
}

Champ	Type	Description
id	String	UUID du QR code
tx_id	String	txId BACEN (identifiant du QR dans le SPI)
pix_key	String	Clé PIX du bénéficiaire dans le QR
amount	Integer	Valeur du QR en unités de base (0 si QR sans valeur définie)
fee_amount	Integer	Toujours 0 dans le QR code (les frais sont prélevés à la liquidation)
status	String	paid, pending, expired, cancelled
external_id	String	Identifiant de votre système
description	String	Description renseignée à la création du QR
end_to_end_id	String	E2E du PIX qui a liquidé le QR (uniquement si status=paid). null sinon.
direction	String	Toujours "inbound" pour QR code
type	String	Toujours "pix_qrcode"
created_at	String	Instant de création du QR (ISO 8601)
paid_at	String	Instant du paiement (ISO 8601). null si pas encore payé.

Toutes les valeurs monétaires sont en unités de base (÷ 10 000 pour reais).

Priorité de recherche

Le backend cherche l'external_id dans cet ordre : (1) transactions → shape 1, (2) outbound_requests en vol → shape 2, (3) failed_transactions → shape 3, (4) qrcodes → shape 4. La première table qui contient l'ID l'emporte.

Différences entre shapes (important pour le parser du client)

Les 4 shapes partagent certains champs (ex. : transaction_id, end_to_end_id, external_id, amount, status, type, direction) mais n'ont pas le même ensemble de champs :

• Shape 1 (settled) : 18 champs y compris fee_amount, net_amount, payer_document, payer_ispb, payer_bank_name, recipient_document, recipient_key, counterparty_name
• Shape 2 (processing) : 13 champs — n'apporte pas les données de la contrepartie (payer_document, payer_ispb, recipient_document absents), uniquement ce qui est dans outbound_requests
• Shape 3 (failed) : apporte reason_code + reason_description + objet recipient.{name, key} imbriqué (notez : ce n'est pas recipient_document flat)
• Shape 4 (QR code) : schéma différent — a tx_id, paid_at, pix_key, toujours direction="inbound" et type="pix_qrcode"

Recommandation : inspectez data.status d'abord ; utilisez switch/case pour dispatcher vers 4 parsers distincts. Ne supposez pas la présence de champs cross-shape.

Reçu officiel

Pour générer un reçu formaté (PDF-ready, avec données d'institution et valeurs en BRL formatées), utilisez GET /api/external/transactions/:id/receipt après la liquidation — l'endpoint /transactions/ref/:external_id apporte des données brutes pour la conciliation programmatique, pas le formatage visuel.

Réponse d'erreur -- 404

{
  "worked": false,
  "errors": {
    "not_found": "Transação não encontrada para o external_id informado"
  }
}

Réponse d'erreur -- 401

{
  "worked": false,
  "errors": {
    "unauthorized": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}

Unicité

L'external_id n'est pas unique par compte. Si plusieurs transactions ont le même external_id, l'endpoint retourne la plus récente. Nous recommandons d'utiliser des valeurs uniques pour faciliter la conciliation.