Add JSON items to a PIX batch
Atomically appends 1–50 payments to a DRAFT or REVIEWED batch.
Each item is either a key payment (key, optional keyType —
detected when omitted) or a bank-account payment (name,
documentNumber, bankIspb or bankCode, accountBranch,
accountNumber, accountType). identifier is unique inside the
batch and becomes the identifier of the resulting PIX out
(pix-out-{accountId}-{identifier}), so it must also be unused on
the account.
Any invalid row rejects the whole chunk (400 pix_batch_chunk_invalid
with errors[]); nothing is stored. Repeating an identifier with the
same content is a no-op; with different content it is
409 pix_batch_item_conflict. Adding items to a REVIEWED batch
resets it to DRAFT — review again before dispatch.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
PIX batch identifier (pxb_…) returned by the create endpoint.
Headers
Optional client-generated idempotency token (recommended for safe retries).
Unix seconds. Required on the signed host; tolerance is 300s either way (403 request_timestamp_skew).
Lowercase hex SHA-256 of the body. An empty body hashes the empty string, so the header is always present. Mismatch returns 400 body_hash_mismatch.
Detached JWS (<protected>..<signature>, ES256 or PS256) over METHOD\nPATH?QUERY\nTIMESTAMP\nIDEMPOTENCY_KEY_OR_EMPTY\nX_CONTENT_SHA256.
Request
Response
Entire chunk appended; batch back to DRAFT
Batch identifier (pxb_…).
Optional operator-facing name; empty when omitted.
Batch lifecycle. DRAFT and REVIEWED are editable (editing a
REVIEWED batch returns it to DRAFT). REVIEWING is the asynchronous
pre-flight. Dispatch requires REVIEWED. COMPLETED, PARTIAL_FAILED
and FAILED are terminal and the only states with receipts.
Amount in BRL as a decimal string with two places (1234.56).
Summary written when the review finishes (or aborts).