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.

{
  "allowed_tax_ids": [
    "12345678909"
  ],
  "payments": [
    {
      "amount_in_cents": 11631,
      "description": "Pagamento boleto",
      "external_reference_id": "boleto-001",
      "line": "34191091070544794730971544640008884660000011631",
      "tax_id": "12345678909"
    }
  ]
}

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