API Internet BankingPix

Lookup payment by identifier

Returns the real-time status of an outbound PIX payment by its client-supplied identifier (the value sent in the POST body of the original PIX out). Backed by a live call to the banking partner — no local cache.

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.
X-Request-TimestampstringRequired

Unix seconds. Required on the signed host; tolerance is 300s either way (403 request_timestamp_skew).

X-Content-SHA256stringRequired

Lowercase hex SHA-256 of the body. An empty body hashes the empty string, so the header is always present. Mismatch returns 400 body_hash_mismatch.

X-Request-SignaturestringRequired

Detached JWS (<protected>..<signature>, ES256 or PS256) over METHOD\nPATH?QUERY\nTIMESTAMP\nIDEMPOTENCY_KEY_OR_EMPTY\nX_CONTENT_SHA256.

Query parameters

identifierstringRequired

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}.

Response

Payment details.
transactionIdstring
Internal transaction ID.
statusenum

Canonical transaction status:

  • INITIATED — created, not yet sent to BACEN
  • PENDING_APPROVAL — held inside the settlement bank. Ambiguous on purpose (kept for backward compatibility): it covers both the settlement bank’s internal authorisation queue and its risk review, and it never means an approval is pending on your side or on ours. Read hold to know who is holding the order.
  • PROCESSING — sent to BACEN, awaiting settlement
  • COMPLETED — confirmed by BACEN
  • FAILED — rejected/failed (see error fields)
  • REVERSED — returned/refunded after settlement. The refund details (D-code, amount, date) are not in this payload — see the transaction timeline.
typeenum

Direction:

  • IN — Receipt (credit)
  • OUT — Send (debit)
amountdouble
Transaction amount in BRL. Negative for OUT, positive for IN.
currencyenum
transactionDatedatetime

Transaction date/time in RFC3339 with São Paulo offset (-03:00).

endToEndIdstringOptional
Transaction E2E ID in PIX system.
identifierstringOptional

Client-provided identifier (if any).

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, when available.
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.

transactionTypeenumOptional
Detailed transaction type.
methodenumOptional
How the transfer was made.
descriptionstringOptional
Transaction description.
counterpartyobjectOptional

Transaction counterparty (payer or beneficiary).

payerobjectOptional

Transaction counterparty (payer or beneficiary).

payeeobjectOptional

Transaction counterparty (payer or beneficiary).

balancedoubleOptional

Balance after transaction (when available).

qrcodeIdstringOptional

Linked QR code txid (if transaction from QR code).

qrcodeIdentifierstringOptional
Linked QR code client identifier.
originalEndToEndstringOptional
For refund transactions, the E2E of the original PIX.
refundEndToEndIdslist of stringsOptional
List of refund E2E IDs linked to this transaction.
totalRefundeddoubleOptional
Total amount refunded from this transaction.

Errors

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