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 Params

The body does not accept fields beyond the ones listed (additionalProperties: false). The two tracks are mutually exclusive and the exclusivity is enforced by the schema: sending target_account with bank_slip, digitable_line with ted, 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 when `bank_slip`.	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 when `ted`.	47

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

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.

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.
`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​

target_account Object​

account_type Enumerators​

Response​

Response Body Params​

Errors​