Skip to main content
POST
Create a PIX charge
Split across sub-accounts. The optional split field shares part of the amount with other wallets of yours — sub-accounts, or the main account through the reserved word principal. At most 10 items, fixed amounts in BRL.Whoever creates the charge is the originator: it receives the gross amount, pays the full fee and only then splits, so the cap is the net amount (charge amount minus the fee), not the gross. The split happens at settlement, not at creation. Refunds and MED debit the originator only — whoever received a share is never debited.See Payment Split for the full rules, the examples and the error table.
Choosing the institution. If your account has this option enabled, the optional pspCredentialId field pins the institution that issues this charge, bypassing the configured routing. Copy the ID under Settings → Routing in the dashboard.Pinning is not preferring: if the institution is down or out of capacity, the charge fails instead of going out through another one. The response echoes pspCredentialId as a receipt.See Choosing the Institution for the full rules and the error table.

Authorizations

​
Authorization
string
header
required

Access token obtained from POST /auth (client_id + client_secret). Valid for 300 seconds.

Headers

​
Idempotency-Key
string

Unique client-provided key (8-255 chars) that makes the request idempotent. Retries with the same key return the cached response (24h TTL). The same key with a different body returns 422.

Required string length: 8 - 255
​
X-Sub-Account
string

Reference of the sub-account the operation runs against. When omitted, the operation happens on the main account; the reserved value principal also resolves to the main account and is equivalent to omitting the header. Accepted on every endpoint except POST /auth and the /sub-accounts endpoints themselves, which always operate on the main account.

Possible errors: 404 SUB_ACCOUNT_NOT_FOUND, 403 SUB_ACCOUNT_FORBIDDEN, 403 SUB_ACCOUNT_SUSPENDED.

Requires the credential to have sub-account access enabled (Settings → Integration → API Credentials). It starts turned off and is not replaced by any permission, not even FULL_ACCESS: without it the response is 403 SUB_ACCOUNT_FORBIDDEN.

Pattern: ^[a-z0-9][a-z0-9_-]{1,31}$
Example:

"loja-centro"

Body

application/json
​
amount
number
required

Amount in BRL (e.g. 100.50 for R$ 100,50)

Required range: x >= 1
Example:

150.75

​
description
string
required

Charge description

Maximum string length: 255
Example:

"Pagamento do pedido #12345"

​
customer
object

Payer details (all optional).

​
projectId
string<uuid>

Project ID to associate the transaction with. If omitted, the charge inherits the account's project when there is a single one; with multiple projects the charge is created without a project.

​
pspCredentialId
string<uuid>

Pins the institution that issues this charge, bypassing the configured routing. Use the ID shown under Settings → Routing in the dashboard. It must be an enabled, active institution of your account. If it is down or out of capacity, the charge FAILS — it does not fall back to another one: you asked for this one. Available to accounts with institution choice enabled.

Example:

"6e307aa4-4772-4230-a648-d88cee308f54"

​
expiresIn
integer

Seconds until expiration (default: 86400 = 24h)

Required range: 300 <= x <= 604800
Example:

3600

​
externalReference
string

Your external reference ID

Maximum string length: 255
Example:

"pedido-12345"

​
metadata
object

Custom metadata (key-value pairs)

Example:
​
split
object[]

Shares part of the amount with other sub-accounts of the same account, at settlement. Whoever creates the charge is the originator: it receives the gross amount, pays the full fee and only then splits — the fee is not shared with the recipients. The split sum cannot exceed the net amount (charge amount minus the fee). Refunds and MED debit the originator only; whoever received a share is never debited.

Maximum array length: 10

Response

PIX charge created successfully

​
id
string<uuid>
required

Charge ID (transaction ID)

​
status
enum<string>
required

Charge status

Available options:
pending,
completed,
failed,
cancelled
​
amount
number
required

Amount in BRL

Example:

150.75

​
currency
string
required

Currency code

Example:

"BRL"

​
pixCopyPaste
string
required

PIX copy-and-paste code

Example:

"00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
expiresAt
string<date-time>
required

Expiration date

​
createdAt
string<date-time>
required

Creation date

​
qrCodeBase64
string

PIX QR Code as a data URI (data:image/png;base64,...)

​
pspPaymentId
string

Transaction ID at the payment service provider (PSP). Use it for reconciliation; absent if the PSP did not return the ID at creation.

Example:

"de3516a2-c63a-4c02-b132-a239bf42e183"

​
pspCredentialId
string<uuid>

Institution that issued this charge. Only present when you pinned the institution in the request (pspCredentialId), as a receipt that it was honored.

Example:

"6e307aa4-4772-4230-a648-d88cee308f54"

​
externalReference
string

Your external reference ID

Example:

"pedido-12345"

​
split
object[]

Accepted split, in BRL. Present only when the charge was created with a split — if it came back in the response, the sub-accounts existed and the sum fit in the net amount. What was actually distributed arrives in the payment_completed webhook.