> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://en.docs.api.corpx.com/baas/referencia/pix/upload-pix-batch-csv/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server. # Upload a CSV of items to a PIX batch POST https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/batches/{batchId}/items/csv Content-Type: text/csv 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`. Reference: https://en.docs.api.corpx.com/baas/referencia/pix/upload-pix-batch-csv ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Path parameters - `accountId` (string, required) — Account identifier. - `batchId` (string, required) — PIX batch identifier (`pxb_…`) returned by the create endpoint. ### Headers - `X-Tenant-Id` (string, required) — Tenant context used for authorization and routing. - `Idempotency-Key` (string, optional) — Optional client-generated idempotency token (recommended for safe retries). ### Body (text/csv) This endpoint expects a string. - `string` ## Response ### 200 Entire file appended; batch back to DRAFT - `batchId` (string, required) — Batch identifier (`pxb_…`). - `name` (string, required) — Optional operator-facing name; empty when omitted. - `status` (enum, required) — 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. - Allowed values: `DRAFT`, `REVIEWING`, `REVIEWED`, `QUEUED`, `PROCESSING`, `COMPLETED`, `PARTIAL_FAILED`, `FAILED` - `totalItems` (integer, required) — Number of staged items. - `totalAmount` (string, required) — Amount in BRL as a decimal string with two places (`1234.56`). - `completedItems` (integer, required) — Items settled so far. - `failedItems` (integer, required) — Items failed so far. - `limits` (PixBatchLimits, required) — Effective item limit for this account and where it comes from. - `createdAt` (datetime, required) — Draft creation instant, in UTC. - `updatedAt` (datetime, required) — Last persisted update, in UTC. - `statistics` (PixBatchStatistics, required) — Live item counters and amounts. - `items` (list of PixBatchItem, required) — Current page of items. - `page` (integer, required) — Current item page. - `pageSize` (integer, required) — Requested item page size. - `totalPages` (integer, required) — Number of item pages. - `hasNext` (boolean, required) — Whether another item page exists. - `review` (PixBatchReview, optional) — Summary written when the review finishes (or aborts). - `reviewedAt` (datetime, optional) — Instant the last review finished. - `acknowledgedAt` (datetime, optional) — Instant the caller acknowledged the review at dispatch. - `dispatchedAt` (datetime, optional) — Instant the batch was queued. - `completedAt` (datetime, optional) — Instant every item reached an outcome. ## Errors ### 400 Bad Request Error `pix_batch_csv_invalid` (empty body, unknown header, or invalid rows listed in `errors[]`) or `pix_batch_too_large`. - `errorCode` (string, required) — `pix_batch_chunk_invalid` or `pix_batch_csv_invalid`. - `message` (string, required) — Human-readable summary. - `errors` (list of PixBatchLineErrorsResponseErrorsItems, required) — One entry per rejected row. - `docs` (string, optional) — Link to the error code anchor. ### 403 Forbidden Error `feature_disabled` or `pix_batch_account_disabled`. - `errorCode` (string, required) — Stable machine-readable code. See `ErrorCode` for the known values. - `message` (string, required) — Human-readable explanation (pt-BR). Presentation only; may change. - `docs` (string, optional) — Link to this code in the public error catalogue. - `requestId` (string, optional) — Gateway request id. Quote it when contacting support. - `partner` (ErrorResponsePartner, optional) — Raw error from the settlement bank, when the failure came from it. Diagnostic only. ### 404 Not Found Error `pix_batch_not_found`. - `errorCode` (string, required) — Stable machine-readable code. See `ErrorCode` for the known values. - `message` (string, required) — Human-readable explanation (pt-BR). Presentation only; may change. - `docs` (string, optional) — Link to this code in the public error catalogue. - `requestId` (string, optional) — Gateway request id. Quote it when contacting support. - `partner` (ErrorResponsePartner, optional) — Raw error from the settlement bank, when the failure came from it. Diagnostic only. ### 409 Conflict Error `pix_batch_not_editable` or `pix_batch_item_conflict`. - `errorCode` (string, required) — Stable machine-readable code. See `ErrorCode` for the known values. - `message` (string, required) — Human-readable explanation (pt-BR). Presentation only; may change. - `docs` (string, optional) — Link to this code in the public error catalogue. - `requestId` (string, optional) — Gateway request id. Quote it when contacting support. - `partner` (ErrorResponsePartner, optional) — Raw error from the settlement bank, when the failure came from it. Diagnostic only. ### 413 Content Too Large Error CSV body above 5 MiB (`pix_batch_csv_invalid`). - `errorCode` (string, required) — Stable machine-readable code. See `ErrorCode` for the known values. - `message` (string, required) — Human-readable explanation (pt-BR). Presentation only; may change. - `docs` (string, optional) — Link to this code in the public error catalogue. - `requestId` (string, optional) — Gateway request id. Quote it when contacting support. - `partner` (ErrorResponsePartner, optional) — Raw error from the settlement bank, when the failure came from it. Diagnostic only. ## Types ### PixBatchLimits Effective item limit for this account and where it comes from. - `maxItems` (integer, required) — Maximum number of items per batch (`pixBatch.maxItems`; default 50). - `source` (string, required) — Policy level that set the limit (`default`, `tenant` or `account`). ### PixBatchStatistics Live item counters and amounts. - `total` (integer, required) — Items in the batch. - `pending` (integer, required) — Items not yet started. - `processing` (integer, required) — Items with a PIX out in flight. - `completed` (integer, required) — Items settled. - `failed` (integer, required) — Items that ended without settlement. - `reviewedOk` (integer, required) — Items that passed the review. - `invalid` (integer, required) — Items flagged by the review. - `totalAmount` (string, required) — Amount in BRL as a decimal string with two places (`1234.56`). - `validAmount` (string, required) — Amount in BRL as a decimal string with two places (`1234.56`). - `completedAmount` (string, required) — Amount in BRL as a decimal string with two places (`1234.56`). - `failedAmount` (string, required) — Amount in BRL as a decimal string with two places (`1234.56`). - `progressPercentage` (double, required) — `(completed + failed) / total × 100`; zero when total is zero. ### PixBatchItem One staged payment, its review outcome and its execution result. - `itemId` (string, required) — Batch-local item identifier (`pxi_…`) used by delete and receipt routes. - `line` (integer, required) — Stable order of this item inside the batch (CSV line order). - `identifier` (string, required) — Caller-owned identifier. - `mode` (enum, required) — How the receiver was given. - Allowed values: `KEY`, `BANK_ACCOUNT` - `amount` (string, required) — Amount in BRL as a decimal string with two places (`1234.56`). - `description` (string, required) — Free text sent with the PIX. - `status` (enum, required) — Execution state. - Allowed values: `PENDING`, `PROCESSING`, `COMPLETED`, `FAILED` - `reviewStatus` (enum, required) — Review outcome. - Allowed values: `PENDING`, `OK`, `INVALID` - `receiver` (PixBatchItemReceiver, required) — Receiver as staged (bank-account mode) or as resolved by the review (key mode). - `createdAt` (datetime, required) — Item staging instant, in UTC. - `updatedAt` (datetime, required) — Last item update, in UTC. - `reviewError` (PixBatchItemError, optional) — Stable code plus diagnostic text. - `error` (PixBatchItemError, optional) — Stable code plus diagnostic text. - `paymentId` (string, optional) — PIX out payment id once the item was prepared. - `endToEndId` (string, optional) — End-to-end id when settled. - `transactionId` (string, optional) — Settlement-bank transaction id when settled. - `completedAt` (datetime, optional) — Settlement instant. ### PixBatchReview Summary written when the review finishes (or aborts). - `reviewedAt` (datetime, required) — Instant the review finished, in UTC. - `totalItems` (integer, required) — Items in the batch. - `validItems` (integer, required) — Items that passed every check. - `invalidItems` (integer, required) — Items flagged `INVALID`; they block dispatch. - `totalAmount` (string, required) — Amount in BRL as a decimal string with two places (`1234.56`). - `validAmount` (string, required) — Amount in BRL as a decimal string with two places (`1234.56`). - `balance` (PixBatchReviewBalance, required) — Available balance snapshot taken by the review. - `limits` (list of PixBatchReviewLimit, required) — One entry per cashout window. - `warnings` (list of string, optional) — Non-blocking notices (e.g. balance currently insufficient). - `error` (string, optional) — Present only when the review aborted. ### PixBatchLineErrorsResponseErrorsItems - `line` (integer, required) — Item index (JSON, 1-based) or CSV line number. - `message` (string, required) — What is wrong. - `field` (string, optional) — Offending column, when applicable. ### ErrorResponsePartner Raw error from the settlement bank, when the failure came from it. Diagnostic only. - `code` (string, optional) - `message` (string, optional) - `field` (string, optional) — Field the partner pointed at, when any. ### PixBatchItemReceiver Receiver as staged (bank-account mode) or as resolved by the review (key mode). - `name` (string, optional) — Receiver name. - `documentNumber` (string, optional) — Receiver document; masked when it came from DICT. - `keyType` (string, optional) — Key type (key mode). - `key` (string, optional) — PIX key (key mode). - `bankIspb` (string, optional) — Receiver bank ISPB. - `bankCode` (string, optional) — Receiver bank COMPE code. - `accountBranch` (string, optional) — Receiver branch (bank-account mode). - `accountNumber` (string, optional) — Receiver account number (bank-account mode). - `accountType` (string, optional) — Receiver account type (bank-account mode). ### PixBatchItemError Stable code plus diagnostic text. - `errorCode` (string, required) — Stable machine-readable code. - `message` (string, required) — Human-readable diagnostic; do not branch on it. ### PixBatchReviewBalance Available balance snapshot taken by the review. - `available` (string, required) — Amount in BRL as a decimal string with two places (`1234.56`). - `sufficient` (boolean, required) — Whether `available` covers `validAmount`. - `checked` (boolean, required) — False when the settlement bank did not answer; a warning is added. ### PixBatchReviewLimit Comparison of the batch total with one cashout limit window. - `window` (string, required) — Window label (`daily_out`, `nightly_out`, `monthly`). - `enforced` (boolean, required) — Whether a ceiling is configured for this window. - `limit` (string, required) — Amount in BRL as a decimal string with two places (`1234.56`). - `used` (string, required) — Amount in BRL as a decimal string with two places (`1234.56`). - `available` (string, required) — Amount in BRL as a decimal string with two places (`1234.56`). - `sufficient` (boolean, required) — Whether `available` covers `validAmount` (always true when not enforced). ## Examples **Request** ```json "identifier;amount;description;pixKeyType;pixKey;receiverName;receiverDocument;bankIspb;bankCode;branch;accountNumber;accountType\nfolha-set-001;1436.85;Pagamento setembro;CPF;12345678909;;;;;;;\nfolha-set-002;2500.00;Fornecedor;;;EMPRESA EXEMPLO LTDA;12345678000195;60701190;341;0001;123456;CHECKING\n" ``` **Response** ```json { "batchId": "pxb_3f9c2a1b7d4e5f60718293a4b5c6d7e8", "name": "Folha de setembro", "status": "DRAFT", "totalItems": 2, "totalAmount": "3936.85", "completedItems": 0, "failedItems": 0, "limits": { "maxItems": 50, "source": "default" }, "createdAt": "2026-09-30T13:08:12Z", "updatedAt": "2026-09-30T13:08:40Z", "statistics": { "total": 2, "pending": 2, "processing": 0, "completed": 0, "failed": 0, "reviewedOk": 0, "invalid": 0, "totalAmount": "3936.85", "validAmount": "0.00", "completedAmount": "0.00", "failedAmount": "0.00", "progressPercentage": 0 }, "items": [], "page": 1, "pageSize": 50, "totalPages": 1, "hasNext": false } ``` **SDK Code** ```python Pix_uploadPixBatchCsv_example import requests url = "https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches/batchId/items/csv" payload = "\"identifier;amount;description;pixKeyType;pixKey;receiverName;receiverDocument;bankIspb;bankCode;branch;accountNumber;accountType\\nfolha-set-001;1436.85;Pagamento setembro;CPF;12345678909;;;;;;;\\nfolha-set-002;2500.00;Fornecedor;;;EMPRESA EXEMPLO LTDA;12345678000195;60701190;341;0001;123456;CHECKING\\n\"" headers = { "X-Tenant-Id": "X-Tenant-Id", "Authorization": "Bearer ", "Content-Type": "text/csv" } response = requests.post(url, data=payload, headers=headers) print(response.json()) ``` ```javascript Pix_uploadPixBatchCsv_example const url = 'https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches/batchId/items/csv'; const options = { method: 'POST', headers: { 'X-Tenant-Id': 'X-Tenant-Id', Authorization: 'Bearer ', 'Content-Type': 'text/csv' }, body: '"identifier;amount;description;pixKeyType;pixKey;receiverName;receiverDocument;bankIspb;bankCode;branch;accountNumber;accountType\nfolha-set-001;1436.85;Pagamento setembro;CPF;12345678909;;;;;;;\nfolha-set-002;2500.00;Fornecedor;;;EMPRESA EXEMPLO LTDA;12345678000195;60701190;341;0001;123456;CHECKING\n"' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Pix_uploadPixBatchCsv_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches/batchId/items/csv" payload := strings.NewReader("\"identifier;amount;description;pixKeyType;pixKey;receiverName;receiverDocument;bankIspb;bankCode;branch;accountNumber;accountType\\nfolha-set-001;1436.85;Pagamento setembro;CPF;12345678909;;;;;;;\\nfolha-set-002;2500.00;Fornecedor;;;EMPRESA EXEMPLO LTDA;12345678000195;60701190;341;0001;123456;CHECKING\\n\"") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-Tenant-Id", "X-Tenant-Id") req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "text/csv") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Pix_uploadPixBatchCsv_example require 'uri' require 'net/http' url = URI("https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches/batchId/items/csv") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-Tenant-Id"] = 'X-Tenant-Id' request["Authorization"] = 'Bearer ' request["Content-Type"] = 'text/csv' request.body = "\"identifier;amount;description;pixKeyType;pixKey;receiverName;receiverDocument;bankIspb;bankCode;branch;accountNumber;accountType\\nfolha-set-001;1436.85;Pagamento setembro;CPF;12345678909;;;;;;;\\nfolha-set-002;2500.00;Fornecedor;;;EMPRESA EXEMPLO LTDA;12345678000195;60701190;341;0001;123456;CHECKING\\n\"" response = http.request(request) puts response.read_body ``` ```java Pix_uploadPixBatchCsv_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches/batchId/items/csv") .header("X-Tenant-Id", "X-Tenant-Id") .header("Authorization", "Bearer ") .header("Content-Type", "text/csv") .body("\"identifier;amount;description;pixKeyType;pixKey;receiverName;receiverDocument;bankIspb;bankCode;branch;accountNumber;accountType\\nfolha-set-001;1436.85;Pagamento setembro;CPF;12345678909;;;;;;;\\nfolha-set-002;2500.00;Fornecedor;;;EMPRESA EXEMPLO LTDA;12345678000195;60701190;341;0001;123456;CHECKING\\n\"") .asString(); ``` ```php Pix_uploadPixBatchCsv_example request('POST', 'https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches/batchId/items/csv', [ 'body' => '"identifier;amount;description;pixKeyType;pixKey;receiverName;receiverDocument;bankIspb;bankCode;branch;accountNumber;accountType\\nfolha-set-001;1436.85;Pagamento setembro;CPF;12345678909;;;;;;;\\nfolha-set-002;2500.00;Fornecedor;;;EMPRESA EXEMPLO LTDA;12345678000195;60701190;341;0001;123456;CHECKING\\n"', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'text/csv', 'X-Tenant-Id' => 'X-Tenant-Id', ], ]); echo $response->getBody(); ``` ```csharp Pix_uploadPixBatchCsv_example using RestSharp; var client = new RestClient("https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches/batchId/items/csv"); var request = new RestRequest(Method.POST); request.AddHeader("X-Tenant-Id", "X-Tenant-Id"); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "text/csv"); request.AddParameter("text/csv", "\"identifier;amount;description;pixKeyType;pixKey;receiverName;receiverDocument;bankIspb;bankCode;branch;accountNumber;accountType\\nfolha-set-001;1436.85;Pagamento setembro;CPF;12345678909;;;;;;;\\nfolha-set-002;2500.00;Fornecedor;;;EMPRESA EXEMPLO LTDA;12345678000195;60701190;341;0001;123456;CHECKING\\n\"", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Pix_uploadPixBatchCsv_example import Foundation let headers = [ "X-Tenant-Id": "X-Tenant-Id", "Authorization": "Bearer ", "Content-Type": "text/csv" ] let postData = NSData(data: ""identifier;amount;description;pixKeyType;pixKey;receiverName;receiverDocument;bankIspb;bankCode;branch;accountNumber;accountType\nfolha-set-001;1436.85;Pagamento setembro;CPF;12345678909;;;;;;;\nfolha-set-002;2500.00;Fornecedor;;;EMPRESA EXEMPLO LTDA;12345678000195;60701190;341;0001;123456;CHECKING\n"".data(using: String.Encoding.utf8)!) let request = NSMutableURLRequest(url: NSURL(string: "https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches/batchId/items/csv")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```