# Pix 收款 (/zh/docs/conta-digital/charges)

<QuickLinks>
  <QuickLink href="/docs/conta-digital/endpoints/charges/post_payment" title="创建 Pix 收款" method="POST" path="/transactions/payment" />

  <QuickLink href="/docs/conta-digital/endpoints/charges/get_payment" title="查询收款" method="GET" path="/transactions/payment/{paymentId}" />

  <QuickLink href="/docs/conta-digital/endpoints/charges/post_payment_refund" title="收款退款" method="POST" path="/transactions/payment/{paymentId}/refund" />
</QuickLinks>

<Mermaid
  chart="`
flowchart LR
  A[&#x22;创建收款&#x22;] --> B[&#x22;展示 Pix 复制粘贴码&#x22;]
  B --> C[&#x22;客户付款&#x22;]
  C --> D[&#x22;PAYMENT_PAID Webhook&#x22;]
  D --> E[&#x22;放行订单&#x22;]

  click A &#x22;/docs/conta-digital/endpoints/charges/post_payment&#x22; &#x22;创建收款&#x22;
  click D &#x22;/docs/conta-digital/webhooks&#x22; &#x22;Webhooks&#x22;

  style A fill:#f59e0b,stroke:#d97706,color:#ffffff
  style D fill:#14ce71,stroke:#0eb464,color:#ffffff
  style E fill:#14ce71,stroke:#0eb464,color:#ffffff
`"
/>

<Steps>
  <Step>
    ### 创建收款 [#创建收款]

    [`POST /transactions/payment`](/docs/conta-digital/endpoints/charges/post_payment)，作用域 `PAYMENT_WRITE`。必填：以分为单位的 `amount`、`method: "PIX"` 和客户信息，即 `customer.name` 和 `customer.document`（CPF 或 CNPJ）。

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

    <Tabs items="['curl', 'Node.js']">
      <Tab value="curl">
        ```bash
        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"
            }
          }'
        ```
      </Tab>

      <Tab value="Node.js">
        ```ts
        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();
        ```
      </Tab>
    </Tabs>

    `description` 会展示给付款人。`metadata` 会在这笔收款的 Webhook 中返回。`callbackUrl` 接收这笔收款的 Webhook，需要[回调密钥](/docs/conta-digital/webhooks#操作的-callbackurl)。所有字段见[创建 Pix 收款](/docs/conta-digital/endpoints/charges/post_payment)。
  </Step>

  <Step>
    ### 向客户展示 Pix [#向客户展示-pix]

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

    ```json
    {
      "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`）。
  </Step>

  <Step>
    ### 付款时放行订单 [#付款时放行订单]

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

    随时核对：用响应中的 `id` 或 Webhook 中的 `paymentId` 查询 [`GET /transactions/payment/{paymentId}`](/docs/conta-digital/endpoints/charges/get_payment)。
  </Step>
</Steps>

## 收款状态 [#收款状态]

<Mermaid
  chart="`
stateDiagram-v2
  [*] --> PENDING
  PENDING --> PAID: 已支付
  PENDING --> EXPIRED: 已过期
  PAID --> REFUNDED: 全额退款
  REFUNDED --> [*]
  EXPIRED --> [*]
`"
/>

| 状态         | 含义                    |
| ---------- | --------------------- |
| `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` 中。 |
| 第一笔仍在处理中时使用相同的 `externalRef` | `412` `PAYMENT_CREATION_IN_FLIGHT`。几秒后再试。                         |

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

## 查询与凭证 [#查询与凭证]

* **列表：**[`GET /transactions/payment`](/docs/conta-digital/endpoints/charges/get_payments)，可按状态、期间、`externalRef` 和客户筛选。
* **凭证：**[`GET /transactions/payment/{paymentId}/receipt`](/docs/conta-digital/endpoints/charges/get_payment_receipt) 以 base64 返回 PDF，适用于已支付或已退款的收款。

## 退款 [#退款]

[`POST /transactions/payment/{paymentId}/refund`](/docs/conta-digital/endpoints/charges/post_payment_refund)，作用域 `REFUND`。发送 `amount` 可退还部分金额；不传 `amount` 时，退还全部剩余金额。

```json
{ "amount": 1000 }
```

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

## 限额 [#限额]

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

各路由的拒绝及其 `code` 见[创建 Pix 收款](/docs/conta-digital/endpoints/charges/post_payment)和[退款](/docs/conta-digital/endpoints/charges/post_payment_refund)。