PayZuDocs

Pix 收款

查看 Markdown
PortuguêsEnglish中文

创建收款，把 Pix 复制粘贴码展示给客户，并在付款到达时放行订单。

POST创建 Pix 收款/transactions/paymentGET查询收款/transactions/payment/{paymentId}POST收款退款/transactions/payment/{paymentId}/refund

创建收款

POST /transactions/payment，作用域 PAYMENT_WRITE。必填：以分为单位的 amount、method: "PIX" 和客户信息，即 customer.name 和 customer.document（CPF 或 CNPJ）。

把你的订单号放在 externalRef 中：用同一个 externalRef 重复调用会返回同一笔收款，而不是再创建一笔。

curl -X POST https://api.hub.payzu.com.br/api/v1/transactions/payment \
  -H "Authorization: Bearer $PAYZU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500,
    "method": "PIX",
    "description": "Pedido 4821",
    "externalRef": "pedido-4821",
    "metadata": { "pedido": "4821", "canal": "checkout-web" },
    "customer": {
      "name": "Maria Souza",
      "document": "52998224725",
      "email": "maria.souza@exemplo.com"
    }
  }'
const res = await fetch('https://api.hub.payzu.com.br/api/v1/transactions/payment', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 1500,
    method: 'PIX',
    description: 'Pedido 4821',
    externalRef: 'pedido-4821',
    metadata: { pedido: '4821', canal: 'checkout-web' },
    customer: {
      name: 'Maria Souza',
      document: '52998224725',
      email: 'maria.souza@exemplo.com',
    },
  }),
});
const cobranca = await res.json();

description 会展示给付款人。metadata 会在这笔收款的 Webhook 中返回。callbackUrl 接收这笔收款的 Webhook，需要回调密钥。所有字段见创建 Pix 收款。

向客户展示 Pix

响应（201）在 pix.qrCodeText 中带有 Pix 复制粘贴码。把它展示给客户，并用它生成二维码。

{
  "id": "hubp-20261005K7Q2M9XB4T127431",
  "status": "PENDING",
  "amount": 1500,
  "serviceFee": 105,
  "netAmount": 1395,
  "externalRef": "pedido-4821",
  "pix": {
    "qrCodeText": "00020126580014br.gov.bcb.pix0136b3c7e9a2-4f1d-4c8a-9e2b-7d5f6a8c1e03520400005303986540515.005802BR5912LOJA EXEMPLO6009SAO PAULO62070503***63041EC4"
  }
}

serviceFee 是手续费，从金额中扣除：一笔 R$ 15,00 的收款、手续费 R$ 1,05，入账 R$ 13,95（netAmount）。

付款时放行订单

客户付款后，会收到 PAYMENT_PAID Webhook，带有你的 externalRef 和创建时的 metadata。在这时放行订单。收款过期未支付时，会收到 PAYMENT_EXPIRED。

随时核对：用响应中的 id 或 Webhook 中的 paymentId 查询 GET /transactions/payment/{paymentId}。

收款状态

状态含义
PENDING等待付款。
PAID已支付。净额已在账户中。
REFUNDED已全额退款。
EXPIRED过期未支付。不会回到 PENDING。

付款后，payer 显示实际付款人，CPF 已脱敏或 CNPJ 已格式化，pix.conciliationId 带有 Pix 的 end-to-end 标识。customer 仍是你填写的客户。

重复请求

你发送API 响应
相同的 externalRef，数据相同200，返回已有的收款。
相同的 externalRef，但有数据不同409 PAYMENT_EXTERNAL_REF_MISMATCH。不一致的字段在 details.fields 中。
第一笔仍在处理中时使用相同的 externalRef412 PAYMENT_CREATION_IN_FLIGHT。几秒后再试。

比较使用金额、方式、描述、metadata 和客户数据。callbackUrl 和 ipAddress 不参与比较。不要在 metadata 中放入每次尝试都会变化的内容。

查询与凭证

退款

POST /transactions/payment/{paymentId}/refund，作用域 REFUND。发送 amount 可退还部分金额；不传 amount 时，退还全部剩余金额。

{ "amount": 1000 }
  • 退款手续费另收，在退还金额之外。
  • 金额和手续费在发起请求时从可用余额中扣出，退款失败时退回。
  • 每笔收款同一时间只能有一笔退款。部分退款可以多次进行，直到达到总金额。
  • 收款存在进行中的 MED 争议时，退款会被拒绝（REFUND_INFRACTION_OPEN）。
  • 结果通过 REFUND_COMPLETED 或 REFUND_FAILED Webhook 送达。
  • 该路由不接受 Idempotency-Key。遇到 502 时，退款可能已经发出：再次请求前先查询收款。

限额

  • 金额必须在账户的最小值和最大值之间，且大于手续费。你的限额见限额。
  • 每个凭证每分钟最多 60 笔收款，每个账户 120 笔。超过后，API 返回 429 和 Retry-After。
  • 退款与提现共用同一个请求次数限制：每个凭证每分钟 5 次，每个账户 10 次。

各路由的拒绝及其 code 见创建 Pix 收款和退款。

WebhooksPix 提现

本页内容

创建收款向客户展示 Pix付款时放行订单收款状态重复请求查询与凭证退款限额