Skip to navigation
API BaaSPix

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

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accountIdstringRequired
Account identifier.
batchIdstringRequired

PIX batch identifier (pxb_…) returned by the create endpoint.

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
Idempotency-KeystringOptional

Optional client-generated idempotency token (recommended for safe retries).

Request

This endpoint expects an object.
itemslist of objectsRequired
Atomic chunk of PIX payments.

Response

Entire chunk appended; batch back to DRAFT

batchIdstring

Batch identifier (pxb_…).

namestring

Optional operator-facing name; empty when omitted.

statusenum

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.

totalItemsinteger0-5000
Number of staged items.
totalAmountstringformat: "^[0-9]+\.[0-9]{2}$"

Amount in BRL as a decimal string with two places (1234.56).

completedItemsinteger
Items settled so far.
failedItemsinteger
Items failed so far.
limitsobject
Effective item limit for this account and where it comes from.
createdAtdatetime
Draft creation instant, in UTC.
updatedAtdatetime
Last persisted update, in UTC.
statisticsobject
Live item counters and amounts.
itemslist of objects
Current page of items.
pageinteger
Current item page.
pageSizeinteger
Requested item page size.
totalPagesinteger
Number of item pages.
hasNextboolean
Whether another item page exists.
reviewobjectOptional

Summary written when the review finishes (or aborts).

reviewedAtdatetimeOptional
Instant the last review finished.
acknowledgedAtdatetimeOptional
Instant the caller acknowledged the review at dispatch.
dispatchedAtdatetimeOptional
Instant the batch was queued.
completedAtdatetimeOptional
Instant every item reached an outcome.

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error