Expense Creation

Create an individual expense under an existing contract. The expense contains the payment data, the accrual period and the supporting documents.

Prerequisites

The referenced contract must exist and cannot be in the rejected status.
The dates (payment_date, start_deferral_date, end_deferral_date) must be business days (no weekends or national holidays).
start_deferral_date cannot be later than end_deferral_date.
When the contract has a contract_value, the sum of the values of all expenses cannot exceed that limit.

Submission shortcut

If the supporting documents are included in the documents field during creation, the expense is automatically forwarded for review (status pending_adm_approval), with no need to call the submission endpoint separately.

Request

ENDPOINT

/expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense

METHOD

POST

Path params

Parameter	Type	Description
`fund_class_key`	string	Unique key of the fund (UUID)
`contract_key`	string	Unique key of the contract

Request Body — Payment by transfer (TED/PIX)
{
    "payment_method": "transfer",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Honorários de auditoria referente ao 1º semestre de 2026",
    "payment_value": 15000.00,
    "payment_date": "2026-07-01",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        },
        "transfer_type": "wire_transfer",
        "source_account": {
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        }
    },
    "documents": [
        {
            "name": "NF-e 001234",
            "document_type": "invoice",
            "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK..."
        }
    ]
}

Request Body — Payment by bankslip
{
    "payment_method": "bank_slip",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Taxa de custódia - junho/2026",
    "payment_value": 3500.00,
    "payment_date": "2026-07-01",
    "payment": {
        "target": {
            "name": "CUSTODIANTE EXEMPLO S.A.",
            "document_number": "98.765.432/0001-10"
        },
        "bank_slip": {
            "digitable_line": "34191.09008 63521.510047 91020.150008 1 10010000035000"
        },
        "source_account": {
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        }
    }
}

Body attributes

Field	Type	Required	Description
`payment_method`	string	required	Payment method: `transfer`, `automatic_debit` or `bank_slip`.
`start_deferral_date`	string	required	Accrual start date in the `YYYY-MM-DD` format. Must be a business day.
`end_deferral_date`	string	required	Accrual end date in the `YYYY-MM-DD` format. Must be a business day and ≥ `start_deferral_date`.
`description`	string	required	Expense description. Maximum of 200 characters.
`payment_value`	number	required	Expense value. Minimum: `0`.
`payment_date`	string	required	Payment date in the `YYYY-MM-DD` format. Must be a business day.
`payment`	object	required	Payment data. See `payment` attributes.
`documents`	array	optional	List of supporting documents. When provided, the expense is automatically forwarded for review. See `documents` attributes.

`payment` attributes

Field	Type	Required	Description
`target`	object	required	Beneficiary data.
`target.name`	string	required	Beneficiary name.
`target.document_number`	string	required	Beneficiary's CPF (`###.###.###-##`) or CNPJ (`##.###.###/####-##`).
`target_account`	object	conditional	Destination bank account data. Required for `payment_method = transfer`.
`target_account.account_number`	string	required	Account number (1-20 digits, cannot be all zeros).
`target_account.account_branch`	string	required	Branch (exactly 4 digits, cannot be all zeros).
`target_account.account_digit`	string	required	Check digit (1 digit).
`target_account.financial_institution_code`	string	required	Bank code (exactly 3 digits, cannot be all zeros).
`target_account.financial_institution_ispb`	string	optional	Bank ISPB (exactly 8 digits).
`target_account.account_type`	string	optional	Bank account type.
`transfer_type`	string	conditional	Transfer type: `pix` or `wire_transfer`. Required for `payment_method = transfer`.
`target_pix_key`	string	conditional	Beneficiary's PIX key (1-77 characters). Required when `transfer_type = pix`.
`pix_qrcode`	string	optional	PIX QR Code (1-255 characters).
`bank_slip`	object	conditional	Bankslip data. Required for `payment_method = bank_slip`.
`bank_slip.digitable_line`	string	required	Digitable line of the bankslip (47-48 characters).
`source_account`	object	optional	Source debit account of the payment.
`source_account.account_key`	string	required	Unique key of the source account (UUID).
`conciliation_metadata`	object	optional	Reconciliation metadata.
`conciliation_metadata.fee_type`	string	optional	Fee type for reconciliation.
`conciliation_metadata.conciliation_value`	string	optional	Reconciliation value.
`conciliation_metadata.conciliation_field`	string	optional	Reconciliation field.

`documents` attributes

Field	Type	Required	Description
`name`	string	required	Document name. Maximum of 255 characters.
`document_type`	string	required	Document type: `invoice`, `calculation_memory`, `contract` or `bank_slip`.
`document_b64`	string	required	Document content encoded in Base64.

Response

STATUS

201

Response Body
{
    "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
    "contract_key": "contrato-auditoria-2026",
    "status": "pending_adm_approval",
    "payment_method": "transfer",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Honorários de auditoria referente ao 1º semestre de 2026",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        },
        "transfer_type": "wire_transfer",
        "source_account": {
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        }
    },
    "payment_value": 15000.00,
    "payment_date": "2026-07-01",
    "rebate_expense_key": null,
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    }
}

Response attributes

Field	Type	Description
`expense_key`	string	Unique key of the expense (UUID). Store this value for the next steps.
`contract_key`	string	Key of the contract the expense belongs to.
`status`	string	Expense status. It will be `pending_adm_approval` if documents were included at creation, or `created` otherwise.
`payment_method`	string	Payment method of the expense.
`start_deferral_date`	string	Accrual start date in the `YYYY-MM-DD` format.
`end_deferral_date`	string	Accrual end date in the `YYYY-MM-DD` format.
`description`	string	Expense description.
`payment`	object	Payment data as sent at creation.
`payment_value`	number	Expense value.
`payment_date`	string	Payment date in the `YYYY-MM-DD` format.
`rebate_expense_key`	string	Key of the original expense when this is a rebate, or `null`.
`fund_class`	object	Data of the associated fund.

Possible errors

STATUS

404

Contract not found

The fund_class_key + contract_key pair does not correspond to any registered contract.

{
  "title": "Contract Not Found",
  "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.",
  "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.",
  "code": "ESB000011"
}

STATUS

400

Rejected contract

It is not possible to create expenses under a contract with the rejected status.

{
  "title": "Cannot Create Expense On Rejected Contract",
  "description": "Cannot create expense on rejected contract {contract_key}.",
  "translation": "Não é possível criar despesa no contrato rejeitado {contract_key}.",
  "code": "ESB000035"
}

Expired contract

The contract's validity date has already passed. It is not possible to create new expenses.

{
  "title": "Contract Expired",
  "description": "Contract {contract_key} has expired.",
  "translation": "O contrato {contract_key} está vencido.",
  "code": "ESB000029"
}

Sum of the expenses exceeds the contract value

The sum of the values of all expenses would exceed the contract_value defined in the contract.

{
  "title": "Expense Value Sum Greater Than Contract",
  "description": "The sum of expense values exceeds the contract value for {contract_name}.",
  "translation": "A soma dos valores das despesas excede o valor do contrato {contract_name}.",
  "code": "ESB000030"
}

Invalid date (not a business day)

The date provided in payment_date, start_deferral_date or end_deferral_date is not a business day.

{
  "title": "Date Invalid For Expense Creation",
  "description": "The date {date} is not a valid workday for expense creation.",
  "translation": "A data {date} não é um dia útil válido para criação de despesa.",
  "code": "ESB000032"
}

Accrual start date later than the accrual end date

The start_deferral_date field is later than the end_deferral_date.

{
  "title": "Start Deferral Date Greater Than End Deferral Date",
  "description": "The start deferral date {start_date} is greater than the end deferral date {end_date}.",
  "translation": "A data de início de competência {start_date} é maior que a data de fim de competência {end_date}.",
  "code": "ESB000033"
}

Next steps

If the documents were included at creation (status pending_adm_approval): wait for the QI Tech analysis.
If the documents were not included (status created):
1. Document upload — add at least one document before submitting.
2. Submit the expense — forward it for QI Tech analysis.

Request​

Path params​

Body attributes​

payment attributes​

documents attributes​

Response​

Response attributes​

Possible errors​

Next steps​

Request

Path params

Body attributes

`payment` attributes

`documents` attributes

Response

Response attributes

Possible errors

Next steps