Pular para o conteúdo principal

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
PerfilHostPermissão exigida
Cedenteassignor-apiEscrita

URL base de cada host: Ambientes (Hosts).

Request​

ENDPOINT
/transaction_reversal/fund_class/{fund_class_key}/transaction_reversal
MÉTODO
POST

Path Params​

CampoTipoDescrição
fund_class_keystringChave ú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​

CampoTipoObrigatoriedadeDescrição
amountnumberobrigatórioValor a ser estornado, em reais, com até duas casas decimais. Mínimo 0.01.
descriptionstringobrigatórioDescrição do estorno. Até 100 caracteres.
reversal_typestringobrigatórioTipo de estorno: pix, wire_transfer (TED) ou reversal_conciliation.
reference_datestringobrigatórioData de referência no formato YYYY-MM-DD. Não pode ser anterior à data contábil atual do fundo.
source_account_keystringcondicionalChave (UUID) da conta do fundo de onde sai o estorno. Informe este campo ou source_account.
source_accountAccountcondicionalDados da conta do fundo de onde sai o estorno. Alternativa a source_account_key.
transaction_keystringcondicionalChave (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_accountAccountcondicionalConta de destino do estorno, quando não se usa transaction_key.
target_pix_keystringcondicionalChave Pix de destino. Aceita somente com reversal_type: pix.
origin_keystringopcionalSeu identificador (UUID) do pedido. Um segundo pedido com o mesmo origin_key é recusado (TRV000033).
reference_keystringopcionalChave de referência da transferência a estornar no banco de origem (UUID).
conciliation_fieldstringopcionalCampo para conciliação em múltiplas expectativas.
end_to_end_idstringopcionalIdentificador end-to-end do Pix a estornar.
external_keystringopcionalChave única da transação a estornar no banco de origem (UUID).
bank_slip_settlement_group_keystringopcionalChave única da liquidação de boleto a estornar no banco de origem (UUID).
Atenção
  • Origem: informe exatamente um entre source_account_key e source_account.
  • Destino: informe exatamente um entre transaction_key, target_account e target_pix_key.

Nenhum ou mais de um devolve erro 400.

Account​

CampoTipoDescriçãoCaracteres
account_numberstringNúmero da contaAté 20
account_digitstringDígito da conta1
account_branchstringAgência da contaAté 4
financial_institutionFinancial InstitutionInstituição financeira-
ownerOwnerTitular da conta-

Financial institution​

CampoTipoDescriçãoCaracteres
ispbstringIdentificador de Sistema de Pagamentos Brasileiro8
codestringCódigo da instituição financeira3
namestringNome da instituição financeiraAté 255

Owner​

CampoTipoDescriçãoCaracteres
namestringNome do titularAté 255
document_numberstringCPF ou CNPJ do titular, com pontuação14 ou 18

Response​

STATUS
201

A 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"
}
CampoTipoDescrição
transaction_reversal_keystringIdentificador do estorno na QI Tech (UUID).
statusstringpending_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_accountobjectContas de origem e de destino resolvidas.
fund_classobjectDados do fundo.

Erros​

StatusCódigoQuando acontece
409TRV000033Já existe pedido com este origin_key. Não reenvie: o estorno já foi solicitado.
400TRV000020reference_date anterior à data contábil do fundo.
400TRV000019reversal_type inválido.
400TRV000009amount com mais de duas casas decimais.
400TRV000015 / TRV000016Conta de origem ausente, ou informada de mais de uma forma.
400TRV000017 / TRV000018Destino ausente, ou informado de mais de uma forma.
404TRV000013A conta de origem não foi encontrada.
404TRV000021A transaction_key não foi encontrada na conta de origem.
400TRV000022A transação não está pendente de conciliação (já foi conciliada ou estornada).
400TRV000023A transação não tem os dados da conta de quem enviou; informe target_account.
400TRV000025target_pix_key enviado com reversal_type diferente de pix.
404TRV000026A chave Pix de destino não foi encontrada.
404TRV000005A fund_class_key não existe.
403TRV000012O fundo não está associado ao seu cadastro de cedente.
400QIT000001Corpo 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.