Skip to navigation

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

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accountIdstringRequiredformat: "uuid"
Account ID.

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.

Query parameters

identifierstringOptional

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.

endToEndstringOptional

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.

waitForFinalStatusintegerOptional0-10

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

X-Wait-SecondsintegerOptional

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.

partnerIdstring

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.

endToEndIdstring

BACEN end-to-end ID. Empty while the settlement bank has not assigned one.

identifierstring
Identifier echoed by the settlement bank. On a PIX out, the one you sent.
directionstring

OUT when the account in the path paid, IN when it received. Empty when the settlement bank payload does not tell the sides apart.

statusenum

Canonical status. COMPLETED, FAILED and REVERSED are final — the values waitForFinalStatus waits for.

  • INITIATED — created, not yet sent to BACEN
  • PENDING_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; read hold.
  • PROCESSING — sent to BACEN, awaiting settlement
  • COMPLETED — confirmed by BACEN
  • FAILED — rejected; the settlement bank reason is in errorMessage
  • REVERSED — returned after settlement
  • UNKNOWN — settlement bank status we do not map yet; the raw value is in partnerStatus
amountdouble

Amount in BRL, always positive. direction gives the side.

currencyenum
Allowed values:
descriptionstring
Message attached to the PIX. May be empty.
initiationstring

How the PIX was started, as the settlement bank labels it: pix-key, manual, static-qr-code or dynamic-qr-code. May be empty.

errorMessagestring

Settlement bank reason when status is FAILED. Empty otherwise.

reversalboolean

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.

originalEndToEndstring

End-to-end of the refunded PIX. Empty for the same reason as reversal.

occurredAtdatetime

Transaction time in RFC 3339 with São Paulo offset (-03:00).

payerobject or null

Who paid. null when the settlement bank sends nothing about this side.

beneficiaryobject or null

Who received. null when the settlement bank sends nothing about this side.

errorCodestringOptional

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.

partnerStatusstringOptional

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.

partnerStatusIdintegerOptional
Numeric status code at the settlement bank. Present only when it is not zero.
holdobjectOptional

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.

Errors

400
Bad Request Error
404
Not Found Error
500
Internal Server Error