执行 PIX 退款

PIX 退款可在收款后 90 天内进行。

请求

ENDPOINT

/account/ACCOUNT_KEY/alias/ALIAS_KEY/pix_transfer/PIX_TRANSFER_KEY/reversal

MÉTODO

POST

请求路径参数

字段	类型	描述	字符数
account_key	string	账户唯一密钥（UUIDv4）。	36
alias_key	string	Alias 唯一密钥（UUIDv4）。	36
pix_transfer_key	string	QI 系统中 PIX 转账的标识密钥（UUIDv4）。	36

请求体

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

请求体

字段	类型	描述	字符数
request_control_key*	string	请求唯一密钥（UUIDv4）。	36
reversal_amount*	number	退款金额。	11
reversal_reason*	string	退款原因。	reversal_reason 枚举值
reversal_message	string	退款消息。	140

reversal_reason 枚举值

枚举值	描述
client_request	账户所有者要求退款时使用。
reconciliation	因操作错误进行对账时使用。

响应

响应体

字段	类型	描述	字符数
reversal_status	string	退款交易状态枚举值。可以是 'pending'、'sent' 和 'rejected'。	36
transfer_amount	number	退款转账金额。	11
pix_transfer_key	string	退款中执行的 PIX 交易密钥（UUIDv4）。	36
end_to_end_id	string	SPI（即时支付系统）中 PIX 交易的幂等性密钥。	32
request_control_key	string	客户使用的请求唯一标识密钥（UUIDv4）。	36
created_at	string	退款日期和时间。	---

STATUS

201 created

响应体：已发送退款

{
  "reversal_status": "sent",
  "transfer_amount": 147.00,
  "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"
}

STATUS

202

信息

如果返回的 pix_transfer_status 为 pending 状态，则不应重试 PIX 请求。该转账将被重新处理。需要通过 PIX 转账查询来检查转账状态。

响应体：待处理退款

{
  "reversal_status": "pending",
  "transfer_amount": 147.00,
  "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"
}

STATUS

4XX

响应体：已拒绝退款

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

STATUS

400

信息

除以下所列错误外，PIX 退款还可能收到 PIX 交易 中定义的其他错误。

HTTP 状态码	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