---
title: "Creates a batch of boleto payments."
method: POST
path: "/v1/boleto-payments"
tags: ["Boleto Payments"]
---

# Creates a batch of boleto payments.

`POST /v1/boleto-payments`

## External Reference IDs
Each payment must have a unique `external_reference_id` within the bank account.
Attempting to create a payment with a duplicate `external_reference_id` will fail with 400 Bad Request.

## Idempotency
- **With X-Idempotency-Key header**: Multiple requests with the same idempotency key return the same batch (safe retries).
- **Without X-Idempotency-Key header**: Each request creates a new batch. Duplicate `external_reference_id` values will fail.

## Amount Handling
- If `amount_in_cents` is provided, it will be used for the payment.
- If `amount_in_cents` is null, the amount will be extracted from the barcode line during processing.

## Uniqueness Scope
The `external_reference_id` is unique per bank account, not globally. Different accounts can use the same `external_reference_id`.

## Allowed Beneficiaries (allowed_tax_ids)
When `allowed_tax_ids` is provided, it acts as an allowlist that restricts which beneficiary documents are accepted for the entire batch.
The `tax_id` in each payment must be present in the list.
When empty, payments to any document are accepted.

## Headers

- `X-Idempotency-Key` string, nullable

## Request body

- CreateBoletoPaymentsRequest
  - `allowed_tax_ids` string[] — Optional list of CPF/CNPJ that restricts the allowed beneficiary documents for this batch. When provided, the `tax_id` in each payment must be present in the list. When empty, payments to any document are accepted.
  - `payments` BoletoPaymentRequest[], required — Boleto payments to create in this batch (1–100 items).
    - `amount_in_cents` integer, nullable — Payment amount in centavos. Optional — if omitted, the amount is extracted from the barcode during processing.
    - `description` string, nullable — Payment description (1–255 characters).
    - `external_reference_id` string, nullable — Client-provided unique reference for this payment within the account (1–127 characters).
    - `line` string, required — Boleto barcode line (47 or 48 digits). Supports standard boletos and utility bills (concessionárias).
    - `scheduled_date` string, date, nullable — Scheduled execution date (`YYYY-MM-DD`, America/São Paulo). Must be after today's date in that timezone.
    - `tax_id` string, required — Beneficiary CPF or CNPJ (with or without formatting).

## Response `201`

Boleto payments batch created successfully

- CreateBoletoPaymentsResponse
  - `batch` BatchResponse, required
    - `allowed_tax_ids` string[] — List of CPF/CNPJ that restricts the allowed beneficiary documents for this batch. Empty if unrestricted.
    - `created_at` string, date-time, required — Batch creation timestamp (UTC, RFC 3339).
    - `id` integer, required
    - `idempotency_key` string, nullable
    - `origin_bank_account_id` integer, required
    - `payment_type` 'pix_transfer' | 'boleto_payment', required
    - `status` 'created' | 'ready' | 'scheduled' | 'cancelled' | 'completed' | 'partially_failed' | 'failed', required
    - `total_amount_in_cents` integer, required
    - `total_items` integer, required
  - `payments` BoletoPaymentItemResponse[], required
    - `amount_in_cents` integer, nullable
    - `barcode_line` string, required
    - `created_at` string, date-time, required — Payment creation timestamp (UTC, RFC 3339).
    - `description` string, nullable
    - `external_reference_id` string, nullable
    - `failed_message` string, nullable
    - `id` integer, required
    - `scheduled_date` string, date, nullable — Scheduled execution date (`YYYY-MM-DD`). Null when executed immediately.
    - `status` 'awaiting_approval' | 'pending' | 'processing' | 'success' | 'cancelled' | 'failed', required
    - `tax_id` string, required
    - `transaction_id` integer, nullable

## Other responses

- `400` — Invalid request. Error codes: INVALID_REQUEST (field validation in error.details), DUPLICATE_EXTERNAL_REFERENCE_ID, TOO_MANY_ITEMS, INVALID_AMOUNT, TAX_ID_NOT_IN_ALLOWED_LIST, VALIDATION_ERROR, DUPLICATE_BATCH
- `401` — Authentication failed
- `403` — Access denied
- `404` — No account found
- `409` — Idempotency conflict — same X-Idempotency-Key with different payload. Error code: IDEMPOTENCY_CONFLICT
- `500` — Internal server error

---

[API](https://skmtc.net/kiwify/apis/conta-digital-api.md) · [All operations](https://skmtc.net/kiwify/apis/conta-digital-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kiwify/conta-digital-api/versions/5e009b25c245/schema)