Skip to navigation
API Internet BankingPix

Upload a CSV of items to a PIX batch

Appends every data row of a CSV in the template vocabulary to a DRAFT or REVIEWED batch, atomically. Send the raw file as the body (Content-Type: text/csv), up to 5 MiB. The header is matched by column name (order-insensitive, case-insensitive); ; and , separators are detected; amount accepts 1234.56, 1.234,56 or R$ 1.234,56. The trailing errorCode/errorMessage columns of a correction export are ignored, so the file downloaded from GET .../items/export can be fixed and re-uploaded as is.

Any invalid row rejects the whole file (400 pix_batch_csv_invalid with errors[]). More rows than limits.maxItems is 400 pix_batch_too_large. Same identifier rules as PUT .../items.

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).

X-Request-TimestampstringRequired

Unix seconds. Required on the signed host; tolerance is 300s either way (403 request_timestamp_skew).

X-Content-SHA256stringRequired

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.

X-Request-SignaturestringRequired

Detached JWS (<protected>..<signature>, ES256 or PS256) over METHOD\nPATH?QUERY\nTIMESTAMP\nIDEMPOTENCY_KEY_OR_EMPTY\nX_CONTENT_SHA256.

Request

This endpoint expects a string.

Response

Entire file 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
413
Content Too Large Error