从其他网关迁移
接入过 Pix 网关的开发者都能认出每一项操作。下表列出每项操作在这里的位置。
逐项对照 #
| 您原来的操作 | 在这里 |
|---|---|
| 创建收款或动态 QR 码 | PUT /v2/cob/{txid}。txid 由您生成。 |
| 查询一笔收款 | GET /v2/cob/{txid} |
| 列出收款 | GET /v2/ex/cobrancas |
| 取消一笔未支付的收款 | 取决于账户：GET /v2/ex/config 中的 capacidades.cancelarCobranca。为 false 时，请让收款自然过期。 |
| 转账、payout、Pix 转出 | PUT /v2/ex/pix/{idEnvio}。idEnvio 由您生成。取决于账户：capacidades.saque。 |
| 查询一笔 payout | GET /v2/ex/pix/{idEnvio} |
| 退还一笔到账款项 | PUT /v2/pix/{e2eId}/devolucao/{id}。取决于账户：capacidades.devolucao 为 false 时，该路由返回 503 capacidade_indisponivel。 |
| 余额 | GET /v2/ex/saldo |
| 对账单或资金变动 | GET /v2/ex/extrato/{data} 和 GET /v2/ex/transacoes |
| 配置 webhook | PUT /v2/ex/webhook |
| 重新发送丢失的 webhook | POST /v2/ex/webhook/reenvios 或事件流 GET /v2/ex/eventos |
| 子账户 | PUT /v2/ex/subcontas/{id}，以及查询中的 ?subconta= |
| 争议 | GET /v2/ex/infracoes 和事件 med.infracao.*。冻结显示在 GET /v2/ex/saldo（bloqueado.med）和 GET /v2/ex/bloqueios 中。申辩方式取决于账户：GET /v2/ex/config 中的 capacidades.med。 |
| 用任意 id 查找交易 | GET /v2/ex/transacoes/mapear?ref= |
六个可能让您损失资金的差异 #
- 金额是十进制字符串。
150和150.0会被拒绝；"150.00"会被接受。不要在您这边转换为数字。 - 没有生成 QR 码的接口。
pixCopiaECola在PUT /v2/cob/{txid}的响应中返回，用同一个txid重复调用会返回同一个 QR 码。 - 请在收到
pix.creditado时为您的客户入账，而不是在收到pix.recebido时。前者是余额；后者仍可能被冻结或退回。 - 我们对收到的 Pix 的拒绝会以带有
motivo的devolucao.criada送达。请把您针对motivo的switch中的default分支当作由我们决定的退款处理。 422是响应，不是故障：立即重复会得到同样的422。请按title处理。有些错误在余额或日期变化后可以通过，例如saldo_insuficiente和limite_excedido。- 在您的限额中设为
"0.00"会取消您自定义的上限，而机构的上限仍然有效。不存在没有限额的账户。