创建退款申请

为基金账户中收到的款项创建退款（退回）申请。申请在付款前需经过 QI Tech 的验证，付款结果通过退款 webhook 通知。

适用范围

角色	主机	所需权限
转让方	`assignor-api`	写入

各主机的 Base URL：环境（主机）。

Request

ENDPOINT

/transaction_reversal/fund_class/{fund_class_key}/transaction_reversal

MÉTODO

POST

Path Params

字段	类型	描述
`fund_class_key`	string	基金在 QI DTVM 中的唯一标识 key

Request Body
{
    "amount": 125.25,
    "description": "Estorno - transferência indevida",
    "reversal_type": "pix",
    "reference_date": "2025-01-01",
    "source_account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e",
    "transaction_key": "4208d7d1-9077-4d00-aa4a-a4368b954867",
    "origin_key": "0f8b6c2e-3d1a-4e5f-9a7b-2c4d6e8f0a1b"
}

Body Params

字段	类型	是否必填	描述
`amount`	number	必填	退款金额，以雷亚尔为单位，最多两位小数。最小值 `0.01`。
`description`	string	必填	退款描述。最多 100 个字符。
`reversal_type`	string	必填	退款类型：`pix`、`wire_transfer`（TED）或 `reversal_conciliation`。
`reference_date`	string	必填	参考日期，格式为 `YYYY-MM-DD`。不得早于基金当前的会计日期。
`source_account_key`	string	条件必填	退款付出方基金账户的 key（UUID）。填写此字段或 `source_account`。
`source_account`	Account	条件必填	退款付出方基金账户的数据。可替代 `source_account_key`。
`transaction_key`	string	条件必填	要退款的收款交易的 key（UUID）。款项会退回到汇款方账户。该交易必须处于待对账状态。
`target_account`	Account	条件必填	不使用 `transaction_key` 时的退款目标账户。
`target_pix_key`	string	条件必填	目标 Pix key。仅在 `reversal_type: pix` 时接受。
`origin_key`	string	可选	您为该申请设定的标识（UUID）。使用相同 `origin_key` 的第二个申请会被拒绝（`TRV000033`）。
`reference_key`	string	可选	要退款的转账在原银行中的参考 key（UUID）。
`conciliation_field`	string	可选	用于多笔预期款项对账的字段。
`end_to_end_id`	string	可选	要退款的 Pix 的 end-to-end 标识。
`external_key`	string	可选	要退款的交易在原银行中的唯一 key（UUID）。
`bank_slip_settlement_group_key`	string	可选	要退款的 Boleto 清算在原银行中的唯一 key（UUID）。

注意

来源：在 source_account_key 和 source_account 中只能填写一个。
目标：在 transaction_key、target_account 和 target_pix_key 中只能填写一个。

一个都不填或填写多个都会返回 400 错误。

Account

字段	类型	描述	字符数
`account_number`	string	账号	最多 20
`account_digit`	string	账户校验位	1
`account_branch`	string	账户所属分行	最多 4
`financial_institution`	Financial Institution	金融机构	-
`owner`	Owner	账户持有人	-

Financial institution

字段	类型	描述	字符数
`ispb`	string	巴西支付系统标识（ISPB）	8
`code`	string	金融机构代码	3
`name`	string	金融机构名称	最多 255

Owner

字段	类型	描述	字符数
`name`	string	持有人名称	最多 255
`document_number`	string	持有人的 CPF 或 CNPJ，带标点	14 或 18

Response

STATUS

201

响应会回显所发送的字段，并附加以下数据。

Response Body
{
    "transaction_reversal_key": "b6da1a84-5bb3-4d71-9912-cbbcfe7189c1",
    "amount": 125.25,
    "status": "pending_validation",
    "reversal_type": "pix",
    "origin_type": "manual",
    "reference_date": "2025-01-01",
    "description": "Estorno - transferência indevida",
    "source_account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e",
    "source_account": {
        "owner": {
            "name": "Nome do Fundo",
            "document_number": "11.222.333/0001-81"
        },
        "account_digit": "8",
        "account_branch": "0001",
        "account_number": "1234567",
        "financial_institution": {
            "ispb": "32402502",
            "code": "329",
            "name": "QI Sociedade de Crédito Direto"
        }
    },
    "target_account": {
        "owner": {
            "name": "Nome do Remetente",
            "document_number": "969.698.790-03"
        },
        "account_digit": "1",
        "account_branch": "0001",
        "account_number": "7654321",
        "financial_institution": {
            "ispb": "32402502",
            "code": "329",
            "name": "QI Sociedade de Crédito Direto"
        }
    },
    "fund_class": {
        "fund_class_key": "0619574f-2815-419d-8208-630b0dc30487",
        "name": "Nome do Fundo",
        "document_number": "11.222.333/0001-81",
        "accounting_date": "2025-01-01",
        "manager": {
            "name": "EXEMPLO CAPITAL",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "22.333.444/0001-81"
        }
    },
    "transaction_key": "4208d7d1-9077-4d00-aa4a-a4368b954867",
    "origin_key": "0f8b6c2e-3d1a-4e5f-9a7b-2c4d6e8f0a1b"
}

字段	类型	描述
`transaction_reversal_key`	string	该退款在 QI Tech 中的标识（UUID）。
`status`	string	`pending_validation`（等待 QI Tech 验证）或 `pending_expectation_confirmation`（已批准，处理中）。退款 webhook 在退款已支付（`paid`）或在批准后被废弃时发送。在验证中被拒绝的申请会变为 `discarded`，不发送 webhook。
`source_account`, `target_account`	object	解析后的来源账户和目标账户。
`fund_class`	object	基金数据。

错误

状态码	代码	触发条件
409	`TRV000033`	已存在使用该 `origin_key` 的申请。请勿重发：该退款已提交申请。
400	`TRV000020`	`reference_date` 早于基金的会计日期。
400	`TRV000019`	`reversal_type` 无效。
400	`TRV000009`	`amount` 超过两位小数。
400	`TRV000015` / `TRV000016`	缺少来源账户，或以多种方式提供了来源账户。
400	`TRV000017` / `TRV000018`	缺少目标，或以多种方式提供了目标。
404	`TRV000013`	未找到来源账户。
404	`TRV000021`	在来源账户中未找到该 `transaction_key`。
400	`TRV000022`	该交易不处于待对账状态（已对账或已退款）。
400	`TRV000023`	该交易不含汇款方的账户数据；请填写 `target_account`。
400	`TRV000025`	发送了 `target_pix_key`，但 `reversal_type` 不是 `pix`。
404	`TRV000026`	未找到目标 Pix key。
404	`TRV000005`	该 `fund_class_key` 不存在。
403	`TRV000012`	该基金未与您的转让方注册信息关联。
400	`QIT000001`	请求体无效（缺少必填字段、类型错误或包含不接受的字段）。

认证、权限和主机相关错误：参见 API 错误。

Request​

Path Params​

Body Params​

Account​

Financial institution​

Owner​

Response​

错误​