Criando Pedido de Estorno
Cria um pedido de estorno (devolução) de um valor recebido na conta do fundo. O pedido passa por validação da QI Tech antes do pagamento, e o pagamento é notificado pelo webhook de estorno.
Disponível em
| Perfil | Host | Permissão exigida |
|---|---|---|
| Cedente | assignor-api | Escrita |
URL base de cada host: Ambientes (Hosts).
Request
ENDPOINT
/transaction_reversal/fund_class/{fund_class_key}/transaction_reversalMÉTODO
POSTPath Params
| Campo | Tipo | Descrição |
|---|---|---|
fund_class_key | string | Chave única identificadora do fundo na QI DTVM |
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
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
amount | number | obrigatório | Valor a ser estornado, em reais, com até duas casas decimais. Mínimo 0.01. |
description | string | obrigatório | Descrição do estorno. Até 100 caracteres. |
reversal_type | string | obrigatório | Tipo de estorno: pix, wire_transfer (TED) ou reversal_conciliation. |
reference_date | string | obrigatório | Data de referência no formato YYYY-MM-DD. Não pode ser anterior à data contábil atual do fundo. |
source_account_key | string | condicional | Chave (UUID) da conta do fundo de onde sai o estorno. Informe este campo ou source_account. |
source_account | Account | condicional | Dados da conta do fundo de onde sai o estorno. Alternativa a source_account_key. |
transaction_key | string | condicional | Chave (UUID) da transação recebida que será estornada. O valor é devolvido à conta que o enviou. A transação precisa estar pendente de conciliação. |
target_account | Account | condicional | Conta de destino do estorno, quando não se usa transaction_key. |
target_pix_key | string | condicional | Chave Pix de destino. Aceita somente com reversal_type: pix. |
origin_key | string | opcional | Seu identificador (UUID) do pedido. Um segundo pedido com o mesmo origin_key é recusado (TRV000033). |
reference_key | string | opcional | Chave de referência da transferência a estornar no banco de origem (UUID). |
conciliation_field | string | opcional | Campo para conciliação em múltiplas expectativas. |
end_to_end_id | string | opcional | Identificador end-to-end do Pix a estornar. |
external_key | string | opcional | Chave única da transação a estornar no banco de origem (UUID). |
bank_slip_settlement_group_key | string | opcional | Chave única da liquidação de boleto a estornar no banco de origem (UUID). |
Atenção
- Origem: informe exatamente um entre
source_account_keyesource_account. - Destino: informe exatamente um entre
transaction_key,target_accountetarget_pix_key.
Nenhum ou mais de um devolve erro 400.
Account
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
account_number | string | Número da conta | Até 20 |
account_digit | string | Dígito da conta | 1 |
account_branch | string | Agência da conta | Até 4 |
financial_institution | Financial Institution | Instituição financeira | - |
owner | Owner | Titular da conta | - |
Financial institution
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
ispb | string | Identificador de Sistema de Pagamentos Brasileiro | 8 |
code | string | Código da instituição financeira | 3 |
name | string | Nome da instituição financeira | Até 255 |
Owner
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
name | string | Nome do titular | Até 255 |
document_number | string | CPF ou CNPJ do titular, com pontuação | 14 ou 18 |
Response
STATUS
201A resposta ecoa os campos enviados e acrescenta os dados abaixo.
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"
}
| Campo | Tipo | Descrição |
|---|---|---|
transaction_reversal_key | string | Identificador do estorno na QI Tech (UUID). |
status | string | pending_validation (aguarda validação da QI Tech) ou pending_expectation_confirmation (já aprovado, em processamento). O webhook de estorno é enviado quando o estorno é pago (paid) ou quando é descartado depois de aprovado. Um pedido reprovado na validação passa a discarded sem webhook. |
source_account, target_account | object | Contas de origem e de destino resolvidas. |
fund_class | object | Dados do fundo. |
Erros
| Status | Código | Quando acontece |
|---|---|---|
| 409 | TRV000033 | Já existe pedido com este origin_key. Não reenvie: o estorno já foi solicitado. |
| 400 | TRV000020 | reference_date anterior à data contábil do fundo. |
| 400 | TRV000019 | reversal_type inválido. |
| 400 | TRV000009 | amount com mais de duas casas decimais. |
| 400 | TRV000015 / TRV000016 | Conta de origem ausente, ou informada de mais de uma forma. |
| 400 | TRV000017 / TRV000018 | Destino ausente, ou informado de mais de uma forma. |
| 404 | TRV000013 | A conta de origem não foi encontrada. |
| 404 | TRV000021 | A transaction_key não foi encontrada na conta de origem. |
| 400 | TRV000022 | A transação não está pendente de conciliação (já foi conciliada ou estornada). |
| 400 | TRV000023 | A transação não tem os dados da conta de quem enviou; informe target_account. |
| 400 | TRV000025 | target_pix_key enviado com reversal_type diferente de pix. |
| 404 | TRV000026 | A chave Pix de destino não foi encontrada. |
| 404 | TRV000005 | A fund_class_key não existe. |
| 403 | TRV000012 | O fundo não está associado ao seu cadastro de cedente. |
| 400 | QIT000001 | Corpo inválido (campo obrigatório ausente, tipo errado ou campo não aceito). |
Erros de autenticação, permissão e host: veja Erros da API.