> 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/create-pix-batch/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server. # Create a PIX batch POST https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/batches Content-Type: application/json 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). Reference: https://en.docs.api.corpx.com/baas/referencia/pix/create-pix-batch ## 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. ### Headers - `X-Tenant-Id` (string, required) — Tenant context used for authorization and routing. - `Idempotency-Key` (string, required) — Client-generated idempotency token. ### Body (application/json) This endpoint expects an object. - `name` (string, optional) — Optional operator-facing batch name. ## Response ### 200 Idempotent retry; returns the existing batch - `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. ### 201 Empty draft created - `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 `missing_idempotency_key`, malformed JSON, or `name` longer than 120 characters (`invalid_payload`). - `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. ### 403 Forbidden Error `feature_disabled` (tenant) or `pix_batch_account_disabled` (account policy). - `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. ### 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 ### Pix_createPixBatch_example **Request** ```json { "name": "Folha de setembro" } ``` **Response** ```json { "batchId": "string", "name": "string", "status": "DRAFT", "totalItems": 1, "totalAmount": "1436.85", "completedItems": 1, "failedItems": 1, "limits": { "maxItems": 1, "source": "string" }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z", "statistics": { "total": 1, "pending": 1, "processing": 1, "completed": 1, "failed": 1, "reviewedOk": 1, "invalid": 1, "totalAmount": "1436.85", "validAmount": "1436.85", "completedAmount": "1436.85", "failedAmount": "1436.85", "progressPercentage": 1.1 }, "items": [ { "itemId": "string", "line": 1, "identifier": "string", "mode": "KEY", "amount": "1436.85", "description": "string", "status": "PENDING", "reviewStatus": "PENDING", "receiver": { "name": "string", "documentNumber": "string", "keyType": "string", "key": "string", "bankIspb": "string", "bankCode": "string", "accountBranch": "string", "accountNumber": "string", "accountType": "string" }, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z", "reviewError": { "errorCode": "string", "message": "string" }, "error": { "errorCode": "string", "message": "string" }, "paymentId": "string", "endToEndId": "string", "transactionId": "string", "completedAt": "2024-01-15T09:30:00Z" } ], "page": 1, "pageSize": 1, "totalPages": 1, "hasNext": true, "review": { "reviewedAt": "2024-01-15T09:30:00Z", "totalItems": 1, "validItems": 1, "invalidItems": 1, "totalAmount": "1436.85", "validAmount": "1436.85", "balance": { "available": "1436.85", "sufficient": true, "checked": true }, "limits": [ { "window": "string", "enforced": true, "limit": "1436.85", "used": "1436.85", "available": "1436.85", "sufficient": true } ], "warnings": [ "string" ], "error": "string" }, "reviewedAt": "2024-01-15T09:30:00Z", "acknowledgedAt": "2024-01-15T09:30:00Z", "dispatchedAt": "2024-01-15T09:30:00Z", "completedAt": "2024-01-15T09:30:00Z" } ``` **SDK Code** ```python Pix_createPixBatch_example import requests url = "https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches" payload = { "name": "Folha de setembro" } headers = { "Idempotency-Key": "Idempotency-Key", "X-Tenant-Id": "X-Tenant-Id", "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Pix_createPixBatch_example const url = 'https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches'; const options = { method: 'POST', headers: { 'Idempotency-Key': 'Idempotency-Key', 'X-Tenant-Id': 'X-Tenant-Id', Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: '{"name":"Folha de setembro"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Pix_createPixBatch_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches" payload := strings.NewReader("{\n \"name\": \"Folha de setembro\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Idempotency-Key", "Idempotency-Key") req.Header.Add("X-Tenant-Id", "X-Tenant-Id") req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Pix_createPixBatch_example require 'uri' require 'net/http' url = URI("https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Idempotency-Key"] = 'Idempotency-Key' request["X-Tenant-Id"] = 'X-Tenant-Id' request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"Folha de setembro\"\n}" response = http.request(request) puts response.read_body ``` ```java Pix_createPixBatch_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") .header("Idempotency-Key", "Idempotency-Key") .header("X-Tenant-Id", "X-Tenant-Id") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"Folha de setembro\"\n}") .asString(); ``` ```php Pix_createPixBatch_example request('POST', 'https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches', [ 'body' => '{ "name": "Folha de setembro" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', 'Idempotency-Key' => 'Idempotency-Key', 'X-Tenant-Id' => 'X-Tenant-Id', ], ]); echo $response->getBody(); ``` ```csharp Pix_createPixBatch_example using RestSharp; var client = new RestClient("https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches"); var request = new RestRequest(Method.POST); request.AddHeader("Idempotency-Key", "Idempotency-Key"); request.AddHeader("X-Tenant-Id", "X-Tenant-Id"); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"Folha de setembro\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Pix_createPixBatch_example import Foundation let headers = [ "Idempotency-Key": "Idempotency-Key", "X-Tenant-Id": "X-Tenant-Id", "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["name": "Folha de setembro"] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches")! 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() ``` ### Pix_createPixBatch_example **Request** ```json { "name": "Folha de setembro" } ``` **Response** ```json { "batchId": "pxb_3f9c2a1b7d4e5f60718293a4b5c6d7e8", "name": "Folha de setembro", "status": "DRAFT", "totalItems": 0, "totalAmount": "0.00", "completedItems": 0, "failedItems": 0, "limits": { "maxItems": 50, "source": "default" }, "createdAt": "2026-09-30T13:08:12Z", "updatedAt": "2026-09-30T13:08:12Z", "statistics": { "total": 0, "pending": 0, "processing": 0, "completed": 0, "failed": 0, "reviewedOk": 0, "invalid": 0, "totalAmount": "0.00", "validAmount": "0.00", "completedAmount": "0.00", "failedAmount": "0.00", "progressPercentage": 0 }, "items": [], "page": 1, "pageSize": 50, "totalPages": 0, "hasNext": false } ``` **SDK Code** ```python Pix_createPixBatch_example import requests url = "https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches" payload = { "name": "Folha de setembro" } headers = { "Idempotency-Key": "Idempotency-Key", "X-Tenant-Id": "X-Tenant-Id", "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Pix_createPixBatch_example const url = 'https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches'; const options = { method: 'POST', headers: { 'Idempotency-Key': 'Idempotency-Key', 'X-Tenant-Id': 'X-Tenant-Id', Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: '{"name":"Folha de setembro"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Pix_createPixBatch_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches" payload := strings.NewReader("{\n \"name\": \"Folha de setembro\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Idempotency-Key", "Idempotency-Key") req.Header.Add("X-Tenant-Id", "X-Tenant-Id") req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Pix_createPixBatch_example require 'uri' require 'net/http' url = URI("https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Idempotency-Key"] = 'Idempotency-Key' request["X-Tenant-Id"] = 'X-Tenant-Id' request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"name\": \"Folha de setembro\"\n}" response = http.request(request) puts response.read_body ``` ```java Pix_createPixBatch_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") .header("Idempotency-Key", "Idempotency-Key") .header("X-Tenant-Id", "X-Tenant-Id") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"name\": \"Folha de setembro\"\n}") .asString(); ``` ```php Pix_createPixBatch_example request('POST', 'https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches', [ 'body' => '{ "name": "Folha de setembro" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', 'Idempotency-Key' => 'Idempotency-Key', 'X-Tenant-Id' => 'X-Tenant-Id', ], ]); echo $response->getBody(); ``` ```csharp Pix_createPixBatch_example using RestSharp; var client = new RestClient("https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches"); var request = new RestRequest(Method.POST); request.AddHeader("Idempotency-Key", "Idempotency-Key"); request.AddHeader("X-Tenant-Id", "X-Tenant-Id"); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"name\": \"Folha de setembro\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Pix_createPixBatch_example import Foundation let headers = [ "Idempotency-Key": "Idempotency-Key", "X-Tenant-Id": "X-Tenant-Id", "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["name": "Folha de setembro"] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://tenant.api.corpx.com/v1/accounts/accountId/pix/batches")! 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() ```