Skip to navigation
API BaaSPix

Create a PIX batch

Creates an empty DRAFT batch for this account. M2M only (scope pix_out.create); a user token never reaches this surface. Add items in atomic chunks (PUT .../items) or from a CSV (POST .../items/csv), run POST .../review, then POST .../dispatch with acknowledged: true.

Idempotency-Key is required; an exact retry returns the existing batch with 200. The effective item limit for the account is returned in limits.maxItems (default 50, hard cap 5,000).

Authentication

AuthorizationBearer

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

Path parameters

accountIdstringRequired
Account identifier.

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
Idempotency-KeystringRequired>=8 characters

Client-generated idempotency token.

Request

This endpoint expects an object.
namestringOptional<=120 characters

Optional operator-facing batch name.

Response

Idempotent retry; returns the existing batch

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