Third-party disbursement on the operation

This endpoint sets or replaces the third-party disbursement instruction of an operation, stating that the released amount will be paid to a third-party beneficiary (a supplier, for example) instead of the issuer's settlement account.

Feature available on request

Third-party disbursement is not enabled by default. Request the enablement from QI Tech before integrating — without it, the request is refused with COM000062.

Full replacement and change window

The request replaces the whole instruction — there is no partial field update. The instruction can only be set or changed while the operation is in the in_filling status; outside that status the request is refused with COM000010.

Third-party disbursement on the operation (PUT)

Request

ENDPOINT

/commercial_paper/operation/OPERATION-KEY/third_party_disbursement

METHOD

PUT

Path Params

Field	Type	Description	Max Characters
`OPERATION-KEY` *	string	Unique operation key (UUID v4).	36

Request Body — TED

{
    "payment_method": "ted",
    "target_account": {
        "account_branch": "0001",
        "account_number": "4464541",
        "account_digit": "3",
        "financial_institution_ispb": "32402502",
        "financial_institution_code_number": "329",
        "account_type": "checking",
        "owner_document_number": "11.222.333/0001-81",
        "owner_name": "Fornecedor Exemplo LTDA"
    }
}

Request Body — Bank slip

{
    "payment_method": "bank_slip",
    "digitable_line": "34191790010104351004791020150008291070100000000"
}

Request Body — Pix

{
    "payment_method": "pix",
    "pix_key": "52998224725",
    "pix_key_type": "cpf",
    "beneficiary": {
        "person_type": "natural",
        "name": "João da Silva",
        "document_number": "529.982.247-25",
        "street": "Rua das Flores",
        "number": "100",
        "postal_code": "01234-567",
        "city": "São Paulo",
        "state": "SP",
        "is_pep": false
    }
}

Request Body Params

The body does not accept fields beyond the ones listed (additionalProperties: false). The three tracks are mutually exclusive and the exclusivity is enforced by the schema: sending the field of one track alongside another, omitting the required field of the chosen track, or sending an unknown field returns QIT000001.

Field	Type	Description	Max Characters
`payment_method` *	string	Payment track used in the disbursement.	payment_method Enumerators
`target_account`	object	Beneficiary bank account. Required when `payment_method` is `ted`; forbidden on the other tracks.	target_account Object
`digitable_line`	string	Digitable line of the beneficiary's bank slip, digits only (pattern `^[0-9]{47}$`). Required when `payment_method` is `bank_slip`; forbidden on the other tracks.	47
`pix_key`	string	Beneficiary's Pix key, unformatted for CPF and CNPJ. Required when `payment_method` is `pix`; forbidden on the other tracks.	77
`pix_key_type`	string	Declared type of the Pix key. Required when `payment_method` is `pix`; forbidden on the other tracks.	pix_key_type Enumerators
`beneficiary`	object	Qualification of the third-party beneficiary. Required when `payment_method` is `pix`; optional on `ted` and `bank_slip`.	beneficiary Object

payment_method Enumerators

Value	Description
`ted`	Payment by TED to the account given in `target_account`.
`bank_slip`	Payment of the bank slip given in `digitable_line`.
`pix`	Pix payment to the key given in `pix_key`.

pix_key_type Enumerators

Value	Description
`cpf`	CPF, 11 digits, unpunctuated.
`cnpj`	CNPJ, 14 digits, unpunctuated.
`phone`	Phone number as `+55` followed by 10 or 11 digits.
`email`	Email address, up to 77 characters.
`evp`	Random key (lowercase UUID).

The key format is validated by the schema according to the declared pix_key_type — out of format, QIT000001. For cpf and cnpj the check digits are verified afterwards: right format with wrong check digits returns COM000071.

target_account Object

Field	Type	Description	Max Characters
`account_branch` *	string	Beneficiary bank account branch, digits only (exactly 4).	4
`account_number` *	string	Beneficiary bank account number, digits only (1 to 20).	20
`account_digit` *	string	Beneficiary bank account digit, digits only (exactly 1).	1
`financial_institution_ispb` *	string	ISPB code of the beneficiary's financial institution, digits only (exactly 8). Determines the TED routing.	8
`financial_institution_code_number`	string or `null`	Code of the beneficiary's financial institution, digits only (3). Optional and not used for routing.	3
`account_type` *	string	Beneficiary account type.	account_type Enumerators
`owner_document_number` *	string	CPF or CNPJ of the account holder, formatted (`000.000.000-00` or `00.000.000/0000-00`). The check digits are validated.	18
`owner_name` *	string	Account holder name (1 to 50 characters).	50

account_type Enumerators

Value	Description
`checking`	Checking account.
`savings`	Savings account.
`salary`	Salary account.
`payment`	Payment account.

beneficiary Object

Identifies the third party receiving the amount. Required on the pix track — a Pix key does not say who is being paid — and optional on ted and bank_slip. It travels with the instruction, is signed together with the operation, and is used in the corporate minute that formalises the payment to the third party.

Only name and document_number are required. Every other field is optional and serves to enrich the beneficiary's qualification in the minute.

Field	Type	Description	Required
`person_type`	string	`natural` (individual) or `legal` (company).	Optional
`name` *	string	Beneficiary name.	Always
`document_number` *	string	CPF or CNPJ, formatted (`000.000.000-00` or `00.000.000/0000-00`).	Always
`street`	string	Street.	Optional
`number`	string	Address number.	Optional
`postal_code`	string	Postal code as `00000-000`.	Optional
`city`	string	City.	Optional
`state`	string	State, two uppercase letters.	Optional
`is_pep`	boolean	Whether the person is a Politically Exposed Person.	Optional
`trading_name`	string	Trading name.	Optional
`cnae_code`	string	CNAE as `00.00-0-00`.	Optional
`company_type`	string	Company type.	Optional
`foundation_date`	string	Foundation date (`YYYY-MM-DD`).	Optional
`neighborhood`	string	Neighborhood.	Optional
`complement`	string	Address complement.	Optional
`document_identification_number`	string	ID document number.	Optional
`marital_status`	string	Marital status.	Optional
`property_system`	string	Marital property system.	Optional
`birthdate`	string	Date of birth (`YYYY-MM-DD`).	Optional
`nationality`	string	Nationality.	Optional
`mother_name`	string	Mother's name.	Optional
`father_name`	string	Father's name.	Optional
`occupation`	string	Occupation.	Optional

The more you send, the fuller the minute

With person_type, the minute gains the beneficiary's qualification. With street, number, postal_code, city and state — all five —, it gains the formatted address. Sending only name and document, the minute names the beneficiary without qualifying or addressing it: nothing fails, the document is simply leaner.

TED — check the ISPB

The destination institution of the TED is determined by the financial_institution_ispb. A wrong ISPB sends the money to the wrong institution even if the financial_institution_code_number is correct.

Bank slip — the amount must match the released amount

The bank slip amount is read from the last 10 digits of the digitable line, in cents, and must be equal to the operation's financial.released_amount. Any difference is refused with COM000061.

Because the calculated released_amount differs from the requested amount due to fees, the practical path is: create the operation, read the released_amount from the response, and only then attach a bank slip for that exact amount. Do not rewrite the amount of a real digitable line — that invalidates its check digits and the bank slip stops being payable.

One commercial paper pays exactly one beneficiary, for the full amount: payment splitting is not supported.

Response

STATUS

200

The response carries the full operation object, in the same shape returned by the operation query by key.

Response Body

{
    "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814",
    "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127",
    "operation_type": "commercial_paper",
    "operation_status": "in_filling",
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issuer_name": "Dynamic Enterprises",
    "issuer_document_number": "28.980.395/0001-55",
    "issuer_bank_account": {
        "account_type": "checking",
        "account_digit": "3",
        "account_branch": "0001",
        "account_number": "4464541",
        "financial_institution_ispb": "32402502",
        "financial_institution_code_number": "329"
    },
    "financial": {
        ...
    }
}

Response Body Params

Field	Type	Description
`tenant_key` *	string	Unique tenant key.
`operation_key` *	string	Unique operation key.
`operation_status` *	string	Operation status.
`issuer_key` *	string	Unique issuer key.
`issuer_name` *	string	Issuer name.
`issuer_document_number` *	string	Issuer document number.
`financial` *	object	Operation financial data.

info

The instruction appears in the operation object as third_party_disbursement, in the same shape it was sent. When the operation has no third-party disbursement, the key is omitted from the response — it is not returned as null.

Errors

The codes below are also described in the error catalog.

Code	HTTP	Description
`QIT000001`	400	Schema failure — for example, `payment_method` missing or outside the enum, an invalid combination of `target_account` and `digitable_line`, a `digitable_line` outside the 47-digit pattern, or an unknown field in the body.
`COM000010`	400	Operation cannot be updated outside the `in_filling` status.
`COM000061`	400	Bank slip amount differs from the operation's `released_amount`.
`COM000062`	400	Third-party disbursement is not enabled.
`COM000063`	400	Beneficiary document is invalid.
`COM000071`	400	`pix_key` of type `cpf`/`cnpj` has invalid check digits.
`COM000007`	404	Operation not found.
`COM000008`	403	Operation does not belong to the requesting tenant.

Third-party disbursement on the operation (PUT)​

Request​

Path Params​

Request Body Params​

payment_method Enumerators​

pix_key_type Enumerators​

target_account Object​

account_type Enumerators​

beneficiary Object​

Response​

Response Body Params​

Errors​