申请已收 Pix 的退款

Pix 退款可在收到后 90 天内执行。

请求

ENDPOINT

/account/ACCOUNT_KEY/pix_transfer/PIX_TRANSFER_KEY/reversal

方法

POST

Path Params

字段	类型	描述	字符数
account_key *	uuidv4	账户的唯一标识键。	36
pix_transfer_key *	uuidv4	QI 系统中 Pix 转账的唯一标识键。	36

Request Body

{
  "request_control_key": "303393bf-8f2e-4ff0-b326-ee7ad612e8ca",
  "reversal_amount": 147,
  "reversal_reason": "client_request",
  "reversal_message": "Mensagem Pix da Devolução"
}

Request Body

字段	类型	描述	字符数
request_control_key *	uuidv4	请求唯一键。	36
reversal_amount *	number	退款金额。	11
reversal_reason *	string	退款原因。	Enumerador reversal_reason
reversal_message	string	退款消息。	140

Enumerador reversal_reason

枚举值	描述
client_request	由账户所有人申请时。
reconciliation	因操作错误进行对账时。

响应

STATUS

201

Response Body: 已发送退款

{
  "reversal_status": "sent",
  "transaction_amount": 147,
  "pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
  "end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
  "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
  "created_at": "2021-10-22T20:30:23.459Z"
}

STATUS

202

Response Body: 待处理退款

{
  "reversal_status": "pending",
  "transaction_amount": 147,
  "pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
  "end_to_end_id": "E32402502202407112211Id9JbxoaiTf",
  "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
  "created_at": "2021-10-22T20:30:23.459Z"
}

信息

如果返回 HTTP Status 202 且 pix_transfer_status 字段值为 pending，则不应重试 Pix 申请。

该转账将被重新处理。需要通过查询 Pix 转账来检查转账状态。

Response Body

字段	类型	描述	字符数
reversal_status	enumerator	退款交易状态枚举。	Enumerador reversal_status
transfer_amount	number	退款转账金额。	11
pix_transfer_key	uuidv4	退款执行的 Pix 交易键。	36
end_to_end_id	string	SPI（即时支付系统）内 Pix 交易的幂等键	32
request_control_key	uuidv4	客户端使用的请求唯一标识键。	36
created_at	string	退款日期和时间。	10

Enumerador reversal_status

枚举值	描述
sent	Pix 转账成功。
pending	Pix 转账待处理。
rejected	Pix 转账已拒绝。

STATUS

4xx

Response Body: 退款被拒绝

{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "end_to_end_id": "E32402502202407112211Id9JbxoaiTf",
      "pix_transfer_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  }
}

信息

除了之前为 Pix 转账列出的错误外，Pix 退款还可能返回以下错误。

HTTP 状态码 status	QI 代码 code	标题 title	描述（英文） description	描述（葡文） translation
400	QIT000001	Bad Request	Schema Error	Erro de Schema
404	PXT000018	Reversal Original Transfer not Found	Reversal original pix transfer not found.	Transferência original da devolução não foi encontrada.
400	PXT000017	Reversal Too Great	Reversal transfers sum amount surpasses that of original pix transfer.	A soma das transferências de devolução ultrapassam o valor da transferência pix original.
400	PXT000015	Reversal date expired	Reversal original transaction is older than 90 days	A data de criação da transação original é mais antiga que 90 dias
400	PXT0000127	Invalid Reversal Reason	Reversal reason {reversal_reason} is not valid	Razão de reversão {reversal_reason} não é válida