# 快速开始 (/zh/docs/conta-digital/getting-started)

<QuickLinks>
  <QuickLink href="/docs/conta-digital/endpoints/authentication/post_oauth_token" title="获取访问令牌" method="POST" path="/oauth/token" />

  <QuickLink href="/docs/conta-digital/endpoints/webhooks/post_webhook" title="注册 Webhook 端点" method="POST" path="/transactions/webhooks" />

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

<Mermaid
  chart="`
flowchart LR
  A[&#x22;控制台中的凭证&#x22;] --> B[&#x22;令牌&#x22;]
  B --> C[&#x22;注册 Webhook&#x22;]
  C --> D[&#x22;收款&#x22;]
  D --> E[&#x22;PAYMENT_PAID Webhook&#x22;]

  click A &#x22;https://hub.payzu.com.br&#x22; &#x22;控制台&#x22;
  click B &#x22;/docs/conta-digital/endpoints/authentication/post_oauth_token&#x22; &#x22;获取访问令牌&#x22;
  click C &#x22;/docs/conta-digital/endpoints/webhooks/post_webhook&#x22; &#x22;注册 webhook 端点&#x22;
  click D &#x22;/docs/conta-digital/endpoints/charges/post_payment&#x22; &#x22;创建 Pix 收款&#x22;
  click E &#x22;/docs/conta-digital/webhooks&#x22; &#x22;Webhooks&#x22;

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

<Callout type="warn">
  本指南中的调用都发往生产环境：这里创建的收款是真实的。
</Callout>

<Steps>
  <Step>
    ### 创建凭证 [#创建凭证]

    在数字账户控制台 [hub.payzu.com.br](https://hub.payzu.com.br) 中打开凭证区域，创建一个带有集成所需作用域的凭证。创建时需要输入账户持有人的操作 PIN。

    本指南请勾选 `PAYMENT_WRITE`、`PAYMENT_READ` 和 `WEBHOOK_WRITE`。每个作用域允许的操作见[作用域](/docs/conta-digital/authentication#作用域)。

    页面会显示 `client_id`、`client_secret` 和凭证令牌（`pzu_…`）。

    <Callout type="warn">
      `client_secret` 只显示一次。离开页面前请保存好。
    </Callout>
  </Step>

  <Step>
    ### 用凭证换取令牌 [#用凭证换取令牌]

    把 `client_id` 和 `client_secret` 发送到 [`POST /oauth/token`](/docs/conta-digital/endpoints/authentication/post_oauth_token)。返回的令牌有效期 15 分钟。

    <Tabs items="['curl', 'Node.js']">
      <Tab value="curl">
        ```bash
        curl -X POST https://api.hub.payzu.com.br/api/v1/oauth/token \
          -u "$PAYZU_CLIENT_ID:$PAYZU_CLIENT_SECRET" \
          -d 'grant_type=client_credentials'
        ```
      </Tab>

      <Tab value="Node.js">
        ```ts
        const credentials = Buffer.from(`${process.env.PAYZU_CLIENT_ID}:${process.env.PAYZU_CLIENT_SECRET}`).toString('base64');

        const response = await fetch('https://api.hub.payzu.com.br/api/v1/oauth/token', {
          method: 'POST',
          headers: {
            Authorization: `Basic ${credentials}`,
            'Content-Type': 'application/x-www-form-urlencoded',
          },
          body: 'grant_type=client_credentials',
        });

        const { access_token, expires_in } = await response.json();
        ```
      </Tab>
    </Tabs>

    ```json
    {
      "access_token": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..mQ3Zy1hbVhpbXBsZQ.ZXhlbXBsbw.c2lnbmF0dXJl",
      "token_type": "Bearer",
      "expires_in": 900,
      "scope": "PAYMENT_WRITE PAYMENT_READ WEBHOOK_WRITE"
    }
    ```

    在其他调用中，把 `access_token` 放在 `Authorization: Bearer` 中。下面的示例中，它保存在 `$PAYZU_TOKEN` 里。令牌过期后，API 返回 `401` 和 `TOKEN_INVALID`：在同一路由再获取一个。
  </Step>

  <Step>
    ### 注册 Webhook [#注册-webhook]

    用 [`POST /transactions/webhooks`](/docs/conta-digital/endpoints/webhooks/post_webhook)（作用域 `WEBHOOK_WRITE`）注册你服务器上接收 Webhook 的 URL。URL 必须是 HTTPS 且可公开访问。

    <Tabs items="['curl', 'Node.js']">
      <Tab value="curl">
        ```bash
        curl -X POST https://api.hub.payzu.com.br/api/v1/transactions/webhooks \
          -H "Authorization: Bearer $PAYZU_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{
            "url": "https://sualoja.com.br/webhooks/payzu",
            "events": ["PAYMENT_PAID", "PAYMENT_EXPIRED"]
          }'
        ```
      </Tab>

      <Tab value="Node.js">
        ```ts
        const res = await fetch('https://api.hub.payzu.com.br/api/v1/transactions/webhooks', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            url: 'https://sualoja.com.br/webhooks/payzu',
            events: ['PAYMENT_PAID', 'PAYMENT_EXPIRED'],
          }),
        });
        const { id, secret } = await res.json();
        ```
      </Tab>
    </Tabs>

    `201` 响应带有为每个 Webhook 签名的 `secret`。它只出现在这个响应中：请保存好。也可以在控制台中注册。

    如果返回 `403` 和 `TOKEN_MISSING_SCOPE`，说明凭证缺少某个作用域；缺少的作用域名称在 `details.scope` 中。
  </Step>

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

    用 [`POST /transactions/payment`](/docs/conta-digital/endpoints/charges/post_payment)（作用域 `PAYMENT_WRITE`）创建一笔收款。金额以分为单位：`1500` 即 R$ 15,00。

    <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" }
          }'
        ```
      </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' },
          }),
        });
        const cobranca = await res.json();
        ```
      </Tab>
    </Tabs>

    `201` 响应返回 `status: "PENDING"` 的收款，Pix 复制粘贴码在 `pix.qrCodeText` 中。把它展示给客户，并用它生成二维码。用同一个 `externalRef` 重复调用会返回同一笔收款（`200`），不会再创建一笔。
  </Step>

  <Step>
    ### 接收 `PAYMENT_PAID` [#接收-payment_paid]

    客户付款后，你的服务器会收到 `PAYMENT_PAID`：

    ```http
    POST /webhooks/payzu
    Content-Type: application/json
    X-Payzu-Event: PAYMENT_PAID
    X-Payzu-Delivery: cmu1r7x2k000a01s6h4f2b9qd
    X-Payzu-Timestamp: 1791210790441
    X-Payzu-Signature: sha256=8f3b2c1d...

    {
      "event": "PAYMENT_PAID",
      "id": "cmu1r7x2k000a01s6h4f2b9qd",
      "sentAt": "2026-10-05T14:33:10.441Z",
      "accountId": "cmu0z8k2a000001s6acct0001",
      "data": {
        "paymentId": "cmu2wbljx0000e8gtlic8q1gi",
        "status": "PAID",
        "amount": 1500,
        "serviceFee": 105,
        "netAmount": 1395,
        "metadata": { "pedido": "4821", "canal": "checkout-web" },
        "externalRef": "pedido-4821",
        "endToEndId": "E99999999202610051433a1b2c3d4e5f"
      }
    }
    ```

    用注册 Webhook 时得到的 `secret` 校验签名，方法见 [Webhooks](/docs/conta-digital/webhooks#签名)，并在 10 秒内返回任意 `2xx`。在这里，也就是收到 `PAYMENT_PAID` 时放行订单：创建时的 `externalRef` 和 `metadata` 会在 `data` 中返回。
  </Step>
</Steps>

## 不等 Webhook 直接查询 [#不等-webhook-直接查询]

用 [`GET /transactions/payment/{paymentId}`](/docs/conta-digital/endpoints/charges/get_payment)（作用域 `PAYMENT_READ`）查询收款，使用创建响应中的 `id` 或 Webhook 中的 `paymentId`：

<Tabs items="['curl', 'Node.js']">
  <Tab value="curl">
    ```bash
    curl https://api.hub.payzu.com.br/api/v1/transactions/payment/hubp-20261005K7Q2M9XB4T127431 \
      -H "Authorization: Bearer $PAYZU_TOKEN"
    ```
  </Tab>

  <Tab value="Node.js">
    ```ts
    const res = await fetch('https://api.hub.payzu.com.br/api/v1/transactions/payment/hubp-20261005K7Q2M9XB4T127431', {
      headers: {
        Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
      },
    });
    const cobranca = await res.json();
    ```
  </Tab>
</Tabs>

要查找某个订单的收款，请使用带 `?externalRef=` 的[列出收款](/docs/conta-digital/endpoints/charges/get_payments)。

## 下一步 [#下一步]

<QuickLinks>
  <QuickLink href="/docs/conta-digital/charges" title="Pix 收款" />

  <QuickLink href="/docs/conta-digital/webhooks" title="Webhooks" />

  <QuickLink href="/docs/conta-digital/withdrawals" title="Pix 提现" />

  <QuickLink href="/docs/conta-digital/error-codes" title="错误代码" />
</QuickLinks>