Creating Reversal Request

Creates a reversal (refund) request for an amount received in the fund's account. The request goes through QI Tech validation before payment, and the payment is notified through the reversal webhook.

Available on

Profile	Host	Required permission
Assignor	assignor-api	Write

Base URL for each host: Environments (Hosts).

Request

ENDPOINT

/transaction_reversal/fund_class/{fund_class_key}/transaction_reversal

METHOD

POST

Path Params

Field	Type	Description
fund_class_key	string	Unique identifier key of the fund at 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

Field	Type	Required	Description
amount	number	required	Amount to be reversed, in reais, with up to two decimal places. Minimum 0.01.
description	string	required	Reversal description. Up to 100 characters.
reversal_type	string	required	Reversal type: pix, wire_transfer (TED) or reversal_conciliation.
reference_date	string	required	Reference date in the YYYY-MM-DD format. Cannot be earlier than the fund's current accounting date.
source_account_key	string	conditional	Key (UUID) of the fund account the reversal is paid from. Send this field or source_account.
source_account	Account	conditional	Data of the fund account the reversal is paid from. Alternative to source_account_key.
transaction_key	string	conditional	Key (UUID) of the received transaction to be reversed. The amount is returned to the account that sent it. The transaction must be pending reconciliation.
target_account	Account	conditional	Target account of the reversal, when transaction_key is not used.
target_pix_key	string	conditional	Target Pix key. Only accepted with reversal_type: pix.
origin_key	string	optional	Your identifier (UUID) for the request. A second request with the same origin_key is refused (TRV000033).
reference_key	string	optional	Reference key of the transfer to reverse at the source bank (UUID).
conciliation_field	string	optional	Field for reconciliation across multiple expectations.
end_to_end_id	string	optional	End-to-end identifier of the Pix to reverse.
external_key	string	optional	Unique key of the transaction to reverse at the source bank (UUID).
bank_slip_settlement_group_key	string	optional	Unique key of the bankslip settlement to reverse at the source bank (UUID).

Attention

• Source: send exactly one of source_account_key and source_account.
• Target: send exactly one of transaction_key, target_account and target_pix_key.

None or more than one returns a 400 error.

Account

Field	Type	Description	Characters
account_number	string	Account number	Up to 20
account_digit	string	Account digit	1
account_branch	string	Account branch	Up to 4
financial_institution	Financial Institution	Financial institution	-
owner	Owner	Account holder	-

Financial institution

Field	Type	Description	Characters
ispb	string	Brazilian Payment System Identifier	8
code	string	Financial institution code	3
name	string	Financial institution name	Up to 255

Owner

Field	Type	Description	Characters
name	string	Holder's name	Up to 255
document_number	string	Holder's CPF or CNPJ, with punctuation	14 or 18

Response

STATUS

201

The response echoes the fields sent and adds the data below.

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"
}

Field	Type	Description
transaction_reversal_key	string	Identifier of the reversal at QI Tech (UUID).
status	string	pending_validation (awaiting QI Tech validation) or pending_expectation_confirmation (already approved, being processed). The reversal webhook is sent when the reversal is paid (paid) or when it is discarded after approval. A request rejected in the validation moves to discarded without a webhook.
source_account, target_account	object	Resolved source and target accounts.
fund_class	object	Fund data.

Errors

Status	Code	When it happens
409	TRV000033	A request with this origin_key already exists. Do not resend: the reversal has already been requested.
400	TRV000020	reference_date earlier than the fund's accounting date.
400	TRV000019	Invalid reversal_type.
400	TRV000009	amount with more than two decimal places.
400	TRV000015 / TRV000016	Source account missing, or sent in more than one way.
400	TRV000017 / TRV000018	Target missing, or sent in more than one way.
404	TRV000013	The source account was not found.
404	TRV000021	The transaction_key was not found in the source account.
400	TRV000022	The transaction is not pending reconciliation (it has already been reconciled or reversed).
400	TRV000023	The transaction does not have the sender's account data; send target_account.
400	TRV000025	target_pix_key sent with a reversal_type other than pix.
404	TRV000026	The target Pix key was not found.
404	TRV000005	The fund_class_key does not exist.
403	TRV000012	The fund is not associated with your assignor registration.
400	QIT000001	Invalid body (required field missing, wrong type or field not accepted).

Authentication, permission and host errors: see API Errors.