Skip to main content
POST
Confirm a Pix payment
The organization’s business policies are evaluated again first. You can confirm when they approve the payment (APPROVE, also when no policy matches); when they require approval (NONE), send the payment for approval instead — it is confirmed automatically once approved, and can’t be confirmed by hand meanwhile. Organization admins — API clients included — can confirm whatever the policies decide, and get the verdict back in policy, but not a payment already waiting for approval. When the matching policy approves the payment and tops up the wallet, the top-up runs first — except for a payment for a later day, which is not topped up here (one approved through an approval request is topped up when approved). An organization admin’s confirmation of a payment the policy sends for approval, or refuses, gets no top-up. See Business policies and approvals for the whole flow. The answer depends on the day to pay:
  • 200 — paid now: the payment, now CONFIRMED, and the policies’ verdict in policy. It becomes PAID once the Pix network settles it.
  • 201 — a later day (scheduledAt): the schedule created for it. The payment becomes SCHEDULED; on that day a new payment is created and paid, without the custom fields — in an organization with a required transaction custom field, that payment fails. Cancel the payment to cancel the schedule. Only payments by Pix key or QR code can be scheduled: a payment by bank details for a later day is refused here and stays REQUESTED.
When the payment is refused — for example, for insufficient funds or a limit — it becomes FAILED, with the reason in failReason, and the error is returned. A FAILED payment can’t be retried: create another one. You need permission to pay from the wallet: on the organization’s main wallet, be an organization admin; on another wallet, be an organization admin or have it shared with you as OWNER or USER — and Pix payments must be enabled in its settings.

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

Body

application/json
​
processingType
enum<string>

Leave it out (INSTANT). DELAYED is reserved for the scheduled payments Portão 3 makes on their day.

Available options:
INSTANT,
DELAYED
Example:

"INSTANT"

​
retryCount
integer

Leave it out (0). Reserved for the scheduled payments Portão 3 makes on their day.

Example:

0

Response

Successful response

A Pix payment just confirmed.

​
_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:

"CONFIRMED"

​
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:

123000

​
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"

​
policy
Policy evaluation · object | null
required

The business policy evaluated on this confirmation, and what it decided. null when the payment was confirmed after its approval, and when an organization admin confirmed it while the policies couldn't be evaluated.

​
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