---
title: "Create Transfers"
method: POST
path: "/v1/transfers"
tags: ["PIX"]
---

# Create Transfers

`POST /v1/transfers`

## External Reference IDs
Each transfer must have a unique `external_reference_id` within the bank account.
Attempting to create a transfer 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.

## 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.
- For `pix_key` transfers: the document resolved from the PIX key must match one of the listed values.
- For `bank_account` transfers: the `tax_id` provided in the transfer must be present in the list.
When empty, transfers to any document are accepted.

## Headers

- `X-Idempotency-Key` string, nullable

## Request body

- CreateTransfersRequest
  - `allowed_tax_ids` string[] — Optional list of CPF/CNPJ that restricts the allowed beneficiary documents for this batch. For `pix_key` transfers: the document resolved from the PIX key must match one of the listed values. For `bank_account` transfers: the `tax_id` provided in the transfer must be present in the list. When empty, transfers to any document are accepted.
  - `transfers` TransferRequest[], required — Transfers to create in this batch (1–100 items).
    - union
      - object — Transfer to a PIX key (email, phone, CPF/CNPJ, or random key).
        - `amount_in_cents` integer, required — Amount in centavos (BRL). Must be >= 1.
        - `display_description` string, nullable — Description shown to the beneficiary (max 140 characters).
        - `external_reference_id` string, nullable — Client-provided unique reference for this transfer within the account (1–127 characters).
        - `pix_key` string, required — The PIX key (DICT entry) to pay. Examples by type: - **CPF** (document, digits only — no punctuation): `12345678901` - **CNPJ** (document, digits only — no punctuation): `12345678901234` - **PHONE** (E.164: `+`, country code, number — no spaces/parentheses/dashes): `+5510998765432` - **EMAIL** (lowercase, max 77 chars): `pix@bcb.gov.br` - **EVP** (random key generated by DICT): `123e4567-e89b-12d3-a456-426655440000` Document numbers (CPF/CNPJ) must be sent **without punctuation** and phones must follow the pattern above. Counter-example: `(10) 10998765432` is **invalid** (compare with `+5510998765432`).
        - `pix_key_type` 'cpf' | 'cnpj' | 'email' | 'phone' | 'evp'
        - `scheduled_date` string, date, nullable — Scheduled execution date (`YYYY-MM-DD`, America/São Paulo). Must be after today's date in that timezone.
        - `type` 'pix_key', required
      - object — Transfer to a bank account using manual bank details.
        - `account_number` string, required — Destination account number.
        - `account_type` 'checking_account' | 'savings_account' | 'payment_account' | 'other_account', required — Account types allowed in the Public API. checking_account, savings_account, payment_account, and other_account are supported.
        - `amount_in_cents` integer, required — Amount in centavos (BRL). Must be >= 1.
        - `branch_code` string, required — Destination branch code.
        - `display_description` string, nullable — Description shown to the beneficiary (max 140 characters).
        - `external_reference_id` string, nullable — Client-provided unique reference for this transfer within the account (1–127 characters).
        - `ispb` string, required — Destination bank ISPB (8 digits).
        - `name` string, nullable — Beneficiary name (optional, but cannot be empty when provided).
        - `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).
        - `type` 'bank_account', required

## Response `201`

Transfers batch created successfully

- CreateTransfersResponse
  - `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
  - `transfers` TransferItemResponse[], required — Individual transfer items in the batch.
    - `amount_in_cents` integer, required — Transfer amount in centavos.
    - `beneficiary` union, required
      - object
        - `pix_key` string, required
        - `resolved_account_number` string, nullable
        - `resolved_account_type` 'checking_account' | 'savings_account' | 'payment_account' | 'other_account' — Account types allowed in the Public API. checking_account, savings_account, payment_account, and other_account are supported.
        - `resolved_branch` string, nullable
        - `resolved_ispb` string, nullable
        - `name` string, nullable
        - `tax_id` string, nullable
      - object
        - `account_number` string, required
        - `account_type` 'checking_account' | 'savings_account' | 'payment_account' | 'other_account' — Account types allowed in the Public API. checking_account, savings_account, payment_account, and other_account are supported.
        - `branch_code` string, required
        - `ispb` string, required
        - `resolved_account_number` string, nullable
        - `resolved_account_type` 'checking_account' | 'savings_account' | 'payment_account' | 'other_account' — Account types allowed in the Public API. checking_account, savings_account, payment_account, and other_account are supported.
        - `resolved_branch` string, nullable
        - `resolved_ispb` string, nullable
        - `name` string, nullable
        - `tax_id` string, nullable
    - `created_at` string, date-time, required — Transfer creation timestamp (UTC, RFC 3339).
    - `display_description` string, nullable — Description shown to the beneficiary.
    - `end_to_end_id` string, nullable — PIX End-to-End ID assigned after successful processing.
    - `external_reference_id` string, nullable — Client-provided reference identifier.
    - `failed_message` string, nullable — Failure reason when status is `failed`.
    - `id` integer, required — Transfer identifier.
    - `scheduled_date` string, date, nullable — Scheduled execution date (`YYYY-MM-DD`). Null when executed immediately.
    - `status` 'awaiting_approval' | 'pending' | 'processing' | 'success' | 'cancelled' | 'failed', required
    - `transaction_id` integer, nullable — Ledger transaction identifier, available after processing.

## 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; JSON errors: WRONG_CONTENT_TYPE, MALFORMED_JSON, INVALID_JSON_BODY
- `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/revisions/5e009b25c245/schema)