Lookup payment by identifier
Returns a PIX payment, sent or received, as the settlement bank
reports it now. Look it up by the identifier you sent on the
PIX out, or by endToEnd. Backed by a live call to the banking
partner. When the settlement bank does not find a payment that
already has a final status at CorpX (completed, refused before
reaching the settlement bank, or returned), the response is 200
with that status.
Pass waitForFinalStatus to hold this call until the payment
reaches COMPLETED, FAILED or REVERSED, or until the wait
expires, instead of polling this endpoint yourself. The response
shape does not change. Only this endpoint accepts the parameter;
GET .../pix/transactions ignores it. The webhook remains the
authoritative outcome; the wait is for callers that need the
result in the same request.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Headers
Query parameters
Client-supplied identifier from the original PIX out request
(1-38 chars [A-Za-z0-9._-]). For BigPix chunks, use the
full chunk identifier {base}#bigpix:{shortId}#chunk:{i}/{n}.
Send identifier, endToEnd or both; without either the
response is 400 missing_identifier. With both, identifier
is tried first and endToEnd is the fallback.
BACEN end-to-end ID of the PIX. Finds received payments too:
it is the lookup the API itself uses to fill the payer of a
paid QR code. endToEndId is accepted as an alias.
Seconds to hold the connection while the server polls the
settlement bank until the payment reaches a final status
(COMPLETED, FAILED or REVERSED). Use this instead of
calling this endpoint in a loop. The first attempt goes out
1 s after the call, inside the wait: right after the POST
the settlement bank usually does not have the payment yet.
Omit it, leave it empty or pass 0 to receive the current
status immediately, as before. The response shape does not
change. A value above 10 is capped at 10; the applied wait
comes back in the X-Wait-Seconds header. A non-integer or
negative value is 400 invalid_payload.
When the wait expires before a final status: if the payment
was read at least once, the last status read comes back with
200. If it was never read, the response is the one of the
last attempt — 404 when the settlement bank did not find
it, or the settlement bank error when that attempt failed. A
definitive refusal from the settlement bank (4xx other than
408 and 429) comes back right away, without waiting.
The response can arrive a few seconds after the wait: an
attempt already in flight when the wait expires is allowed to
finish (up to 5 s). Set your HTTP client timeout to at least
waitForFinalStatus + 10 s — 20 s for
waitForFinalStatus=10.
The webhook is still the authoritative path. This parameter is for the caller that needs the outcome in the same request.
Response headers
Present only when waitForFinalStatus was greater than 0:
the wait that was applied, in seconds, after the cap of 10
— not how long the call took. A request with
waitForFinalStatus=99 returns 10. Also sent on 404
and on settlement bank errors after a wait.
Response
The payment. When waitForFinalStatus is greater than 0,
this is the final status, or the last status read if the wait
expired first.
Operation reference at the settlement bank. The current
settlement bank does not return it on PIX lookups, so it comes
empty; use endToEndId or identifier.
BACEN end-to-end ID. Empty while the settlement bank has not assigned one.
OUT when the account in the path paid, IN when it received.
Empty when the settlement bank payload does not tell the sides
apart.
Canonical status. COMPLETED, FAILED and REVERSED are final
— the values waitForFinalStatus waits for.
INITIATED— created, not yet sent to BACENPENDING_APPROVAL— held inside the settlement bank (its authorisation queue or its risk review). It never means an approval is pending on your side or on ours; readhold.PROCESSING— sent to BACEN, awaiting settlementCOMPLETED— confirmed by BACENFAILED— rejected; the settlement bank reason is inerrorMessageREVERSED— returned after settlementUNKNOWN— settlement bank status we do not map yet; the raw value is inpartnerStatus
Amount in BRL, always positive. direction gives the side.
How the PIX was started, as the settlement bank labels it:
pix-key, manual, static-qr-code or dynamic-qr-code.
May be empty.
Settlement bank reason when status is FAILED. Empty otherwise.
Refund marker. The current settlement bank does not report it
on PIX lookups, so it comes false; refunds show up in the
statement (reversal, originalEndToEnd) and in the webhooks.
End-to-end of the refunded PIX. Empty for the same reason as
reversal.
Transaction time in RFC 3339 with São Paulo offset (-03:00).
Who paid. null when the settlement bank sends nothing about this side.
Who received. null when the settlement bank sends nothing about this side.
Public code of the refusal, the same one the pix.out.failed
webhook carries (e.g. insufficient_funds,
limit_exceeded_transaction, limit_exceeded_daily,
partner_rejected). Present only when status is FAILED.
Branch on this field, not on the errorMessage text.
Raw status at the settlement bank, echoed in a clearly named field
(never in status). Present only when the settlement bank reports
one. These are the settlement bank’s own values and may change
without notice — do not use them in status comparisons; they exist
so you can attach evidence to a support ticket.
Present only while the order is held by someone. Today the only
possible owner is the settlement bank, which is exactly the
information PENDING_APPROVAL fails to convey: when this object is
present there is nothing to approve on your side or on ours.