API BaaSPix

Get transaction status by E2E or identifier

Queries the status of a PIX transaction by E2E (End-to-End ID) or identifier. Use this endpoint to check the status of sent (cash out) or received (cash in) transfers. The query searches transactions from the last 90 days. **Important**: Only completed or attempted PIX transfers appear here. QR Codes that were never paid are not transactions (they have no E2E ID). To query QR Code status regardless of payment, use `GET /v1/accounts/{accountId}/pix/qr-code/lookup`. **Search parameters** (at least one is required): - `endToEndId` - Unique transaction identifier in the PIX system - `identifier` - Charge identifier (txid) or internal reference

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

endToEndIdstringOptional

Transaction E2E ID (format E + ISPB + date + sequence).

identifierstringOptional

Charge identifier (txid) or internal reference.

Response

Transaction found.
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