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

{
  "allowed_tax_ids": [
    "12345678909"
  ],
  "transfers": [
    {
      "amount_in_cents": 15000,
      "display_description": "Pagamento fornecedor",
      "external_reference_id": "payroll-2026-05-001",
      "pix_key": "12345678901",
      "pix_key_type": "cpf",
      "type": "pix_key"
    },
    {
      "account_number": "123456",
      "account_type": "payment_account",
      "amount_in_cents": 25000,
      "branch_code": "0001",
      "external_reference_id": "supplier-001",
      "ispb": "00000000",
      "name": "João Silva",
      "tax_id": "12345678909",
      "type": "bank_account"
    }
  ]
}

{
  "batch": {
    "created_at": "2026-05-28T14:30:00Z"
  },
  "transfers": [
    {
      "created_at": "2026-05-28T14:30:00Z",
      "scheduled_date": "2026-06-01"
    }
  ]
}