Skip to main content
POST
Create a Pix charge
What you send decides the kind of charge:
  • No dueDate — a static QR code for txnAmount. It never expires and can’t be canceled. Only the payer’s name is used, at most 25 characters, and description is at most 39.
  • dueDate, with no fine, interest, discount or rebate — a charge payable until the end of expiresAt — or of dueDate, when you omit it — in UTC.
  • dueDate with a fine, interest, discount or rebate — a charge with a due date: paid before dueDate it gets the discount, after it the fine and the interest, and it can be paid until expiresAt. The payer’s bank works out the amount due on the day.
The answer is the charge, status ACTIVE. When it is paid, it moves to PAID with the amount received in confirmedAmount, and your organization’s PIX_BILLING_PAID webhook is sent — see Receive webhooks. Follow it with GET .../pix-billing/{pixId} too. Send forceWallet=true to receive the payment in the wallet in the path. Without it, the QR code is issued for the organization’s main wallet — the payment is credited there, and a charge that belongs to another wallet is never marked PAID. Use default as walletId for the main wallet. The QR code pays into one of the receiving wallet’s active Pix keys, so that wallet needs one. The account’s limits for incoming Pix apply. When the payment institution refuses the charge, or doesn’t answer, after it was recorded, the charge stays CREATING with no QR code (emv): nobody received a code to pay it, so create a new one. When the payment institution throttles the request, the answer is a 429 whose code is the institution’s own reason; retry later. Any member of the organization can create one.

Headers

​
x-environment
enum<string>

Environment of the charge: 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 the charge belongs to (24 hexadecimal characters), or default for the organization's main wallet. Send forceWallet=true too, or the payment goes to the main wallet.

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

Query Parameters

​
forceWallet
enum<string>

Send true to receive the payment in the wallet in the path. When you omit it (or send false), the QR code is issued for the organization's main wallet: the payment is credited there, and a charge that belongs to another wallet is never marked PAID. ?forceWallet with no value counts as true.

Available options:
true,
false,

Body

application/json
​
txnCurrency
enum<string>
required

Currency of the charge, as an ISO 4217 numeric code: always 986 (Brazilian real). The number 986 is accepted too.

Available options:
986
Example:

"986"

​
txnAmount
integer
required

Amount of the charge, in cents.

Required range: x >= 1
Example:

28500

​
txnCanAmountChange
boolean
required

true lets the payer change the amount when paying; false locks it. Not used by a static QR code (no dueDate), which always asks for txnAmount.

Example:

false

​
customer
object
required

The payer. Required for every charge, but a static QR code (no dueDate) uses only its name.

​
dueDate
string

Due date of the charge (YYYY-MM-DD), today or later. Without it, the charge is a static QR code: it never expires and can't be canceled.

Example:

"2026-11-20"

​
expiresAt
string

Last day the charge can be paid (YYYY-MM-DD), on or after dueDate. When you omit it (or send it blank), dueDate is the last day. Not used without dueDate.

Example:

"2026-12-20"

​
description
string

Description of the charge, shown to the payer. At most 39 characters without dueDate (a static QR code).

Example:

"Pedido 4821"

​
txnFineAmount
object | null

Fine charged once when the charge is paid after dueDate. Ignored without dueDate. Omit it for no fine.

​
txnInterestAmount
object | null

Interest charged for each day the charge is paid after dueDate. Ignored without dueDate. Omit it for no interest.

​
txnDiscountAmount
object | null

Discount for paying before dueDate. Ignored without dueDate. Omit it for no discount.

​
txnRebateAmount
object | null

Rebate deducted from the amount whenever the charge is paid. Ignored without dueDate. Omit it for no rebate.

Response

Successful response

A Pix charge: a QR code the payer pays with Pix to credit the wallet.

​
_id
string
required

ID of the charge.

Example:

"672a1f4eb4d3e80012c9b3e7"

​
environment
enum<string>
required

LIVE (production) or TEST (sandbox).

Available options:
LIVE,
TEST
Example:

"LIVE"

​
realmId
string
required

ID of the realm.

Example:

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

​
organizationId
string
required

ID of the organization.

Example:

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

​
accountId
string
required

ID of the account.

Example:

"66f2a1c7b4d3e80012c9a0b4"

​
walletId
string
required

ID of the wallet the charge belongs to.

Example:

"66f2a3d1b4d3e80012c9a0d2"

​
status
enum<string>
required

CREATING while the QR code is being issued — one that stays CREATING never got its QR code (emv) back, so it can't be shown to a payer; ACTIVE once it can be paid; PAID once paid; CANCELED once canceled.

Available options:
CREATING,
ACTIVE,
PAID,
CANCELED
Example:

"ACTIVE"

​
txnCurrency
string
required

Currency of the charge: 986 (Brazilian real).

Example:

"986"

​
txnAmount
number
required

Amount of the charge, in cents.

Example:

28500

​
txnCanAmountChange
boolean
required

Whether the payer can change the amount when paying.

Example:

false

​
txnFineAmount
object | null
required

Fine charged once when the charge is paid after dueDate. When it has none: null, or an amount of 0 (a static QR code keeps the object it was created with).

​
txnInterestAmount
object | null
required

Interest charged for each day the charge is paid after dueDate. When it has none: null, or an amount of 0 (a static QR code keeps the object it was created with).

​
txnDiscountAmount
object | null
required

Discount for paying before dueDate. When it has none: null, or an amount of 0 (a static QR code keeps the object it was created with).

​
txnRebateAmount
object | null
required

Rebate deducted from the amount. When it has none: null, or an amount of 0 (a static QR code keeps the object it was created with).

​
dueDate
string<date-time> | null
required

Due date of the charge — midnight UTC when it was sent as YYYY-MM-DD. null for a static QR code.

Example:

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

​
expiresAt
string<date-time> | null
required

Last day the charge can be paid — midnight UTC when it was sent as YYYY-MM-DD. null when you didn't send one.

Example:

"2026-12-20T00:00:00.000Z"

​
description
string
required

Description of the charge. Empty when you didn't send one.

Example:

"Pedido 4821"

​
customer
object
required

The payer.

​
confirmedAmount
number
required

Amount paid, in cents. 0 until the charge is PAID.

Example:

0

​
confirmedAmountAuthorized
number
required

Not used: always 0.

Example:

0

​
createdAt
string<date-time>
required

When the charge was created.

Example:

"2026-11-05T18:21:34.112Z"

​
updatedAt
string<date-time>
required

When the charge last changed.

Example:

"2026-11-05T18:21:35.004Z"

​
__v
number
required

Version of the record.

Example:

0

​
emv
string

The Pix Copia e Cola code: render it as a QR code or let the payer paste it in their bank's app. Absent while CREATING.

Example:

"00020101021226900014br.gov.bcb.pix2568qrcodes.exemplo.com.br/v2/cobv/b8c1d3e54f2a4c6b9d7e1a2b3c4d5e6f5204000053039865802BR5915Loja Exemplo6009Sao Paulo62070503***6304A1B2"

​
key
string

The Pix key the charge pays into — one of the receiving wallet's active keys. Absent while CREATING.

Example:

"financeiro@lojaexemplo.com.br"

​
confirmedAt
string<date-time>

When the payment was received. Only on a PAID charge.

Example:

"2026-11-18T14:32:07.512Z"

​
canceledAt
string<date-time>

When the charge was canceled. Only on a CANCELED charge.

Example:

"2026-11-19T09:15:42.087Z"

​
external
object

References of the charge at the payment institution. Absent while CREATING.