Skip to main content
POST
Create a Pix payment
Identify the recipient by a Pix key (DICT), a Pix Copia e Cola code or QR code (emv), or bank details (credit_party). The answer brings who you’re about to pay (creditParty), the amount the payment asks for (txnUpdatedAmount — for a QR code, with its discount, fine and interest applied as of now; it isn’t refreshed later) and the payment’s details as far as they are known (pendingConfirmation). It also brings policy: what the organization’s business policies say about the payment as it stands. With actions.autoAction APPROVE you can confirm it; with NONE it needs approval — send it for approval; with DENY it is refused. When the amount or the balance category are still missing (a QR code with an open amount, or no category), set them with PUT .../pix/{pixId} first — its answer carries the policies’ updated verdict. See Business policies and approvals for the whole flow. Send scheduledAt with a later day to have the confirmation schedule the payment for that day. 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 wallet: LIVE (production) or TEST (sandbox). When you omit it, the payment is created in TEST; 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)$

Body

application/json
​
initiationType
enum<string>
required

How you identify the recipient: DICT — a Pix key (send dict, key and amount); COPY_PASTE — a Pix Copia e Cola code, or DYNAMIC_QRCODE, STATIC_QRCODE or UNDEFINED_QRCODE — the code read from a QR code of that kind, or of an unknown kind (send the code in emv); FULL_BANK_DETAILS — the recipient's bank account (send credit_party and amount).

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

"DICT"

​
dict
enum<string> | null

Type of the Pix key in key: PHONE, EMAIL, CPF, CNPJ or EVP (random key). Required with DICT.

Available options:
PHONE,
EMAIL,
CPF,
CNPJ,
EVP
Example:

"CNPJ"

​
key
string | null

The Pix key. Required with DICT. PHONE in E.164 (+5511999998888); EMAIL in lowercase; CPF as 11 digits; CNPJ as 14 characters, unformatted and uppercased (the first 12 may be letters); EVP as the random key's UUID.

Example:

"12345678000195"

​
emv
string | null

The Pix Copia e Cola code, or the code read from the QR code. Required with COPY_PASTE, DYNAMIC_QRCODE, STATIC_QRCODE and UNDEFINED_QRCODE.

Example:

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

​
credit_party
object | null

The recipient's bank account. Required with FULL_BANK_DETAILS — document, bank_ispb, branch, accountNumber and accountType are then all required; ignored otherwise.

​
amount
number | null

Amount to pay, in cents — a positive integer. Required with DICT and FULL_BANK_DETAILS. With a QR code, send it only for an open amount (txnAllowAmountChange: true); otherwise it must equal the QR code's amount, and you can leave it out.

Example:

123000

​
category
enum<string>

Balance category of the wallet to charge. FLEX_INTERNATIONAL is the general-purpose one. With it, and an amount the payment already knows, you can confirm or send the payment for approval without PUT .../pix/{pixId} first.

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

"FLEX_INTERNATIONAL"

​
description
string

A note about the payment. With a Pix key or bank details it goes to the recipient with the payment; with a QR code it only stays with the payment's details.

Example:

"Folders da campanha de novembro"

​
scheduledAt

Day to pay, as YYYY-MM-DD (a date-time counts as its UTC day). Omit it, or send today — in timeZone — to pay as soon as the payment is confirmed. A later day makes the confirmation schedule the payment instead. A day before today is rejected, and a QR code charge with a due date (COBV) can only be paid today or on its due date. Payments by bank details (FULL_BANK_DETAILS) can't be scheduled — their confirmation is refused. The payment made on that day doesn't carry the custom fields, so it fails in an organization with a required transaction custom field.

Example:

"2026-11-10"

​
timeZone
string

Time zone that decides what "today" is for scheduledAt. Only America/Sao_Paulo is supported: any other value, or none, is read as America/Sao_Paulo.

Example:

"America/Sao_Paulo"

​
customFields
object

Values of the organization's transaction custom fields, keyed by each field's slug (deactivated fields included). Each value must fit its field's type and options; required fields can be filled in later, before the payment is sent for approval or confirmed. An organization with no transaction custom fields accepts any keys, stored as sent.

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

Example:

Response

Successful response

A Pix payment, with what the organization's business policies say about it.

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

​
policy
Policy evaluation · object
required

The business policy that matches the payment as it stands, and what it decides: the payment can be confirmed right away (APPROVE), it needs approval (NONE) or it is refused (DENY). Informative only — nothing is enforced until the payment is sent for approval or confirmed. Before an amount is known (a QR code with an open amount), it evaluates an amount of zero.

​
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