无收款单的入账 Pix

当有人不经收款单、直接向账户的某个密钥发送 Pix 时，金额作为存款入账，并会收到 DEPOSIT_RECEIVED Webhook。在本页的路由中使用该 Webhook 里的 depositId。

查询

GET /transactions/deposit/{depositId}，作用域 DEPOSIT_READ。

{
  "id": "cmu4a1b2c000001s6xyz98765",
  "method": "PIX",
  "amount": 5000,
  "serviceFee": 50,
  "netAmount": 4950,
  "e2e": "E99999999202610051433a1b2c3d4e5f",
  "receiverPixKey": "b3c7e9a2-4f1d-4c8a-9e2b-7d5f6a8c1e03",
  "payer": { "name": "João Pereira", "document": "***.456.789-**", "bankIspb": "99999999", "bankName": "Banco Exemplo S.A." },
  "paidAt": "2026-10-05T16:10:02.551Z",
  "createdAt": "2026-10-05T16:10:03.120Z",
  "refundedAmount": 0,
  "refundInProgressAmount": 0,
  "refundableAmount": 5000,
  "openInfractionProtocol": null,
  "refunds": []
}

• amount 是付款人发送的金额。netAmount 是入账金额，已扣除手续费（serviceFee）。
• e2e 是 Pix 的 end-to-end 标识。receiverPixKey 是你账户中收到这笔款的密钥。
• payer 是银行提供的付款人信息，CPF 已脱敏或 CNPJ 已格式化。

存款凭证通过 GET /transactions/deposit/{depositId}/receipt 获取，为 base64 编码的 PDF。

退还给付款人

POST /transactions/deposit/{depositId}/refund，作用域 REFUND。资金退回给发送 Pix 的人。发送 amount 可退回部分金额；不传 amount 时，退回全部剩余金额。

{ "amount": 5000 }

• 退款手续费另收，在退回金额之外。它在限额的 refund 中。
• 每笔存款同一时间只能有一笔退回。一笔仍在处理中时，下一笔会以 REFUND_IN_FLIGHT 被拒绝。
• 存款存在进行中的 MED 争议时，退回会以 REFUND_INFRACTION_OPEN 被拒绝。
• 余额不足时，退回会被拒绝。API 退回的金额从不少于请求的金额。
• 200 响应返回存款，退回记录在 refunds 中。结果通过 REFUND_COMPLETED 或 REFUND_FAILED Webhook 送达，以 depositId 代替 paymentId。在此之前，金额显示在 refundInProgressAmount 中；已经退回的金额在 refundedAmount 中。
• 该路由不接受 Idempotency-Key。遇到 502 时，退回可能已经发出：再次请求前先查询存款。

所有拒绝见退回存款。

已发出 Pix 的退回

当提现的收款方退回金额时，这笔入账作为存款登记，可以通过 depositId 查询。大多数情况下会收到 WITHDRAW_REFUND_RECEIVED Webhook，带有该提现的 withdrawId，不收手续费，账单中的条目为 PAYOUT_REFUND_RECEIVED。有时退回会作为普通 Pix 到达：DEPOSIT_RECEIVED Webhook，收取手续费，条目为 DEPOSIT。两种情况都要处理。