Skip to main content
GET
Get a Pix payment
Read status to follow the payment, creditParty for who it pays, txnUpdatedAmount for the amount it asks for and pendingConfirmation for what will be paid. A payment waiting for approval whose deadline passed comes as EXPIRED. Use default as walletId for the organization’s main wallet. Any member of the organization can read it.

Headers

x-environment
enum<string>

Environment of the payment: LIVE (production) or TEST (sandbox). When you omit it, TEST is used; any other value is rejected.

Available options:
LIVE,
TEST

Path Parameters

realmId
string<uuid>
required

ID of your realm.

Format: UUID

organizationId
string<uuid>
required

ID of the organization.

Format: UUID

accountId
string
required

ID of the organization's account (24 hexadecimal characters).

Pattern: ^[0-9a-fA-F]{24}$
walletId
string
required

ID of the wallet that pays (24 hexadecimal characters), or default for the organization's main wallet.

Pattern: ^([0-9a-fA-F]{24}|default)$
pixId
string
required

ID of the Pix payment — its _id (24 hexadecimal characters).

Pattern: ^[0-9a-fA-F]{24}$

Response

Successful response

A Pix payment sent from one of your wallets.

_id
string
required

ID of the payment. Use it as {pixId} in the payment endpoints.

Example:

"6726a4f1b4d3e80012c9a3f1"

environment
enum<string>
required

Environment of the payment: LIVE (production) or TEST (sandbox).

Available options:
LIVE,
TEST
Example:

"LIVE"

realmId
string<uuid>
required

ID of the realm.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

organizationId
string<uuid>
required

ID of the organization.

Example:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

accountId
string
required

ID of the organization's account.

Example:

"66f2a1c7b4d3e80012c9a0b4"

walletId
string
required

ID of the wallet that pays.

Example:

"66f2a3d1b4d3e80012c9a0d2"

initiationType
enum<string>
required

How the payment was started:

  • DICT — by Pix key.
  • DYNAMIC_QRCODE — by a dynamic QR code (a charge, with or without a due date).
  • STATIC_QRCODE — by a static QR code.
  • FULL_BANK_DETAILS — by the recipient's bank details.

A payment started from a Pix Copia e Cola code or a QR code of unknown kind shows the kind the code turned out to be.

Available options:
DICT,
DYNAMIC_QRCODE,
STATIC_QRCODE,
FULL_BANK_DETAILS
Example:

"DICT"

transactionType
enum<string>
required

Kind of payment: TRANSFER (to a Pix key or bank details), PAYMENT (a QR code), CHANGE or WITHDRAWAL (a Pix Troco or Pix Saque QR code). One older payment carries TRANFER.

Available options:
TRANSFER,
CHANGE,
WITHDRAWAL,
PAYMENT,
TRANFER
Example:

"TRANSFER"

status
enum<string>
required

Status of the payment:

  • REQUESTED — created; its details can still be changed, and it can be sent for approval, confirmed or cancelled.
  • PENDING_APPROVAL — waiting for the approvers the business policy names. It is paid once approved.
  • EXPIRED — the approval deadline (approvalExpiresAt) passed while it waited: it wasn't approved in time, or it was approved but the policy's top-up of the wallet failed.
  • SCHEDULED — confirmed for a future day. On scheduledAt, a new payment is created and paid (without this one's custom fields); this one stays SCHEDULED.
  • CONFIRMED — sent to the Pix network; the money left the wallet.
  • PAID — the Pix network settled it.
  • FAILED — the payment was refused, for the reason in failReason.
  • CANCELLED — cancelled before it was paid.
  • REFUNDED — paid, then returned in full or in part by the recipient's bank — see refunds.

One older payment carries PARTIALLY_REFUNDED.

Available options:
REQUESTED,
PENDING_APPROVAL,
CANCELLED,
CONFIRMED,
PAID,
FAILED,
REFUNDED,
SCHEDULED,
EXPIRED,
PARTIALLY_REFUNDED
Example:

"REQUESTED"

txnCurrency
string
required

Currency of the amounts, as an ISO 4217 numeric code: 986 (Brazilian real).

Example:

"986"

txnOriginalAmount
number
required

Amount when the payment was started, in cents: the amount you sent for a payment by key or bank details, or the QR code's original amount. 0 for a QR code with an open amount.

Example:

123000

txnDiscountAmount
number
required

Discount the QR code grants, in cents.

Example:

0

txnFineAmount
number
required

Late fine the QR code charges, in cents.

Example:

0

txnInterestAmount
number
required

Interest the QR code charges, in cents.

Example:

0

txnPurchaseAmount
number
required

Purchase amount of a Pix Troco QR code, in cents.

Example:

0

txnWithdrawalAmount
number
required

Cash amount of a Pix Saque or Pix Troco QR code, in cents.

Example:

0

txnUpdatedAmount
number
required

Amount the payment asks for, in cents — the original amount with the QR code's discount, fine and interest applied — as read when the payment was created. It isn't refreshed afterwards: for a charge whose fine or interest grows by the day, create a new payment to get the current figure. 0 for a QR code with an open amount.

Example:

123000

additionalInfo
object[]
required

Extra information the QR code carries. Empty when it has none.

processingType
enum<string>
required

How the payment was sent: INSTANT (when it was confirmed) or DELAYED (by a schedule, on its day).

Available options:
INSTANT,
DELAYED
Example:

"INSTANT"

confirmedAmount
number
required

Amount sent, in cents. 0 until the payment is confirmed.

Example:

0

refundedAmount
number
required

Total returned so far, in cents, across every return. 0 when nothing was returned.

Example:

0

createdAt
string<date-time>
required

When the payment was created.

Example:

"2026-11-02T13:10:22.000Z"

updatedAt
string<date-time>
required

When the payment last changed.

Example:

"2026-11-02T13:10:22.000Z"

creditParty
object

Who receives the payment. Present on every payment so far.

debitParty
object

The paying account. Present on every payment so far.

description
string | null

Description of the payment, as sent to the Pix network. null or absent when there is none — QR codes may carry their own.

Example:

"Folders da campanha de novembro"

direction
string

Always empty when present. Ignore it.

Example:

""

receipt
object

The Pix network's proof of the payment. Absent on a few older payments.

external
object

References of the payment in the Pix network. Absent on some older payments.

txnAllowAmountChange
boolean

Whether you can choose the amount to pay — true for a QR code with an open amount. When false (or absent, on a few older payments), the amount to pay is txnUpdatedAmount and no other amount is accepted — except that a COBV charge scheduled for its due date may also pay txnOriginalAmount.

Example:

false

qrCodeType
enum<string>

Kind of QR code: STATIC, COB (a charge with no due date) or COBV (a charge with a due date, fine, interest and discount). Only on payments by QR code.

Available options:
STATIC,
COB,
COBV
Example:

"COB"

pixCopyPaste
string

The QR code's Pix Copia e Cola code. Only on payments by QR code.

Example:

"00020101021226870014br.gov.bcb.pix2565qrcode.example.com/v2/cobv/9d36b84f5204000053039865802BR5919GRAFICA AURORA LTDA6009SAO PAULO62070503***6304ABCD"

dueDate
string<date-time> | null

Due date of a QR code charge. null or absent when it has none.

Example:

null

expiresAt
string<date-time> | null

When the QR code stops being payable. null or absent when it doesn't expire.

Example:

null

withdrawal
object

Cash withdrawal or change details of a QR code. Only on payments by QR code.

pendingConfirmation
object

What will be paid. Absent until the amount is known — a QR code with an open amount gets it from PUT .../pix/{pixId} — and on payments created before it existed.

customFields
object

Values of the organization's transaction custom fields, keyed by each field's slug. Absent when the payment has none.


Example: {"cost-center":"CC-1020"}

Example:
requester
object

Who created the payment. Absent on payments created before it was recorded.

scheduledAt
string<date-time>

Day the payment is scheduled for. Absent when it is paid as soon as it is confirmed.

Example:

"2026-11-10T00:00:00.000Z"

scheduledTimeZone
string

Time zone scheduledAt was read in — always America/Sao_Paulo. Present only with scheduledAt.

Example:

"America/Sao_Paulo"

scheduleId
string<uuid>

ID of the schedule created when a payment for a future day was confirmed. Cancel the payment to cancel it.

Example:

"8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f"

policyRequestId
string

ID of the approval request opened when the payment was sent for approval, or of the automatic approval that funded it. Absent otherwise.

Example:

"4d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a"

approvalExpiresAt
string<date-time>

Deadline for the approval: 21:00 (São Paulo time) of the day the payment is for, and at least one hour after it was sent for approval. Present once it was sent for approval.

Example:

"2026-11-03T00:00:00.000Z"

autoResolutionRequestedAt
string<date-time>

When a confirmation first asked for the automatic approval of the matching business policy. Once set, every later confirmation of this payment follows that approval. Absent when no confirmation needed it.

Example:

"2026-11-02T13:12:05.000Z"

autoResolutionInFlightUntil
string<date-time>

While set and in the future, a confirmation is carrying out the matching policy's automatic approval, and cancelling the payment is refused until then.

Example:

"2026-11-02T13:13:35.000Z"

confirmedAt
string<date-time>

When the payment was sent to the Pix network.

Example:

"2026-11-02T13:12:07.000Z"

confirmedBalanceCategory
enum<string>

Balance category of the wallet the payment was charged to.

Available options:
FLEX_NATIONAL,
FLEX_INTERNATIONAL,
FOOD,
GAS,
MOBILITY,
TOLL,
FLEX_NATIONAL_WITHOUT_WITHDRAWALS,
ADS,
SAAS,
HOTEL,
AIRLINES,
TRAVEL,
BLOCKED,
CASHBACK
Example:

"FLEX_INTERNATIONAL"

failReason
string

Why the payment failed, as an error code — for example LIMIT_EXCEEDED, INSUFFICIENT_FUNDS or REJECTED_BY_FRAUD. Only on FAILED payments; some older ones hold a numeric code or an empty string.

Example:

"INSUFFICIENT_FUNDS"

canceledAt
string<date-time>

When the payment was cancelled.

Example:

"2026-11-02T15:40:00.000Z"

refundedAt
string<date-time>

When the latest return happened.

Example:

"2026-11-05T10:30:00.000Z"

refundedReason
string

Why the latest return happened — the same codes as refunds[].reason; some older payments hold them in lowercase.

Example:

"REFUND_REQUST_BY_END_CUSTOMER"

refunds
object[]

Every return of the payment, one entry per return. Absent until the first one.

linkedPix
string

ID of a related payment, on a few older payments only.

Example:

"6726a4f1b4d3e80012c9a3f5"

__v
number

Internal revision counter of the record.

Example:

0