# Authentication (/docs/conta-digital/authentication.en)



<QuickLinks>
  <QuickLink href="/docs/conta-digital/depositos" title="Deposits" />

  <QuickLink href="/docs/conta-digital/saques" title="Withdrawals" />

  <QuickLink href="/docs/conta-digital/glossary" title="Glossary" />

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

Every call to the **Conta Digital API** uses a **Bearer Token** in the `Authorization` header. The token is provided in the [PayZu Dashboard](https://abrirconta.payzu.com.br).

## Header format [#header-format]

Every request requires **two mandatory headers**:

```http
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
```

## Example [#example]

<Tabs items="['curl', 'Node.js', 'Python']">
  <Tab value="curl">
    ```bash
    curl https://pix.payzu.io/v1/user/balance \
      -H "Authorization: Bearer $PAYZU_TOKEN" \
      -H "Content-Type: application/json"
    ```
  </Tab>

  <Tab value="Node.js">
    ```ts
    const res = await fetch('https://pix.payzu.io/v1/user/balance', {
      headers: {
        Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
        'Content-Type': 'application/json',
      },
    });
    const balance = await res.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import os, requests

    res = requests.get(
        'https://pix.payzu.io/v1/user/balance',
        headers={
            'Authorization': f'Bearer {os.environ["PAYZU_TOKEN"]}',
            'Content-Type': 'application/json',
        },
    )
    ```
  </Tab>
</Tabs>

## Important [#important]

* **Keep the token secure**, never share it publicly or commit it to a repository
* **Per-token permissions**, each one carries scopes defined at creation time
* **Token compromised?** Regenerate it immediately in the PayZu Dashboard and revoke the old one

## Error format [#error-format]

Every error response follows the same format. The most important field is `requestId`, which identifies the call in PayZu's internal logs.

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Missing or invalid Bearer token",
  "requestId": "cmp70zh4008dx01s6bwjb5bez"
}
```

| Field        | What it's for                                                |
| ------------ | ------------------------------------------------------------ |
| `statusCode` | HTTP response code                                           |
| `error`      | Short error name                                             |
| `message`    | Description in PT of what happened                           |
| `requestId`  | Unique ID of the call. Send it when opening a support ticket |

## Where to store [#where-to-store]

| Where to store                 | OK?   |
| ------------------------------ | ----- |
| **Google Secret Manager**      | Yes   |
| **AWS Secrets Manager**        | Yes   |
| **HashiCorp Vault**            | Yes   |
| **Environment variable in CI** | Yes   |
| `.env` in production           | No    |
| Front-end (Web, Mobile)        | Never |

## Support [#support]

<QuickLinks>
  <QuickLink href="https://suporte.payzu.com.br/portal/pt-br/newticket?departmentId=1103699000000006907&layoutId=1103699000000074011" title="Open ticket" />

  <QuickLink href="https://suporte.payzu.com.br" title="Support portal" />
</QuickLinks>


# Autenticação (/docs/conta-digital/authentication)



<QuickLinks>
  <QuickLink href="/docs/conta-digital/depositos" title="Depósitos" />

  <QuickLink href="/docs/conta-digital/saques" title="Saques" />

  <QuickLink href="/docs/conta-digital/glossary" title="Glossário" />

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

Toda chamada à **API Conta Digital** usa **Bearer Token** no header `Authorization`. O token é fornecido no [Dashboard PayZu](https://abrirconta.payzu.com.br).

## Formato do header [#formato-do-header]

Toda requisição precisa de **dois headers obrigatórios**:

```http
Authorization: Bearer SEU_TOKEN
Content-Type: application/json
```

## Exemplo [#exemplo]

<Tabs items="['curl', 'Node.js', 'Python']">
  <Tab value="curl">
    ```bash
    curl https://pix.payzu.io/v1/user/balance \
      -H "Authorization: Bearer $PAYZU_TOKEN" \
      -H "Content-Type: application/json"
    ```
  </Tab>

  <Tab value="Node.js">
    ```ts
    const res = await fetch('https://pix.payzu.io/v1/user/balance', {
      headers: {
        Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
        'Content-Type': 'application/json',
      },
    });
    const balance = await res.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import os, requests

    res = requests.get(
        'https://pix.payzu.io/v1/user/balance',
        headers={
            'Authorization': f'Bearer {os.environ["PAYZU_TOKEN"]}',
            'Content-Type': 'application/json',
        },
    )
    ```
  </Tab>
</Tabs>

## Importante [#importante]

* **Mantenha o token seguro**, nunca compartilhe publicamente nem suba em repositório
* **Permissões por token**, cada um carrega escopos definidos no momento da criação
* **Token comprometido?** Regenere imediatamente no Dashboard PayZu e revogue o antigo

## Formato de erro [#formato-de-erro]

Toda resposta de erro segue o mesmo formato. O campo mais importante é o `requestId`, que identifica a chamada nos logs internos da PayZu.

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Missing or invalid Bearer token",
  "requestId": "cmp70zh4008dx01s6bwjb5bez"
}
```

| Campo        | Para que serve                                         |
| ------------ | ------------------------------------------------------ |
| `statusCode` | Código HTTP da resposta                                |
| `error`      | Nome curto do erro                                     |
| `message`    | Descrição em PT do que aconteceu                       |
| `requestId`  | ID único da chamada. Envie ao abrir chamado de suporte |

## Onde guardar [#onde-guardar]

| Onde guardar                   | OK?   |
| ------------------------------ | ----- |
| **Google Secret Manager**      | Sim   |
| **AWS Secrets Manager**        | Sim   |
| **HashiCorp Vault**            | Sim   |
| **Variável de ambiente no CI** | Sim   |
| `.env` em produção             | Não   |
| Front-end (Web, Mobile)        | Nunca |

## Suporte [#suporte]

<QuickLinks>
  <QuickLink href="https://suporte.payzu.com.br/portal/pt-br/newticket?departmentId=1103699000000006907&layoutId=1103699000000074011" title="Abrir ticket" />

  <QuickLink href="https://suporte.payzu.com.br" title="Portal de suporte" />
</QuickLinks>


# 身份认证 (/docs/conta-digital/authentication.zh)



<QuickLinks>
  <QuickLink href="/docs/conta-digital/depositos" title="存款" />

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

  <QuickLink href="/docs/conta-digital/glossary" title="术语表" />

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

**Conta Digital API** 的每个调用都在 `Authorization` header 中使用 **Bearer Token**。Token 由 [PayZu Dashboard](https://abrirconta.payzu.com.br) 提供。

## Header 格式 [#header-格式]

每个请求都需要**两个必填 header**:

```http
Authorization: Bearer SEU_TOKEN
Content-Type: application/json
```

## 示例 [#示例]

<Tabs items="['curl', 'Node.js', 'Python']">
  <Tab value="curl">
    ```bash
    curl https://pix.payzu.io/v1/user/balance \
      -H "Authorization: Bearer $PAYZU_TOKEN" \
      -H "Content-Type: application/json"
    ```
  </Tab>

  <Tab value="Node.js">
    ```ts
    const res = await fetch('https://pix.payzu.io/v1/user/balance', {
      headers: {
        Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
        'Content-Type': 'application/json',
      },
    });
    const balance = await res.json();
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import os, requests

    res = requests.get(
        'https://pix.payzu.io/v1/user/balance',
        headers={
            'Authorization': f'Bearer {os.environ["PAYZU_TOKEN"]}',
            'Content-Type': 'application/json',
        },
    )
    ```
  </Tab>
</Tabs>

## 重要事项 [#重要事项]

* **妥善保管 token**,切勿公开分享或提交到代码仓库
* **token 按权限分配**,每个 token 在创建时都带有指定的作用域
* **token 泄露了?** 立即在 PayZu Dashboard 中重新生成并吊销旧 token

## 错误格式 [#错误格式]

所有错误响应都遵循同样的格式。最重要的字段是 `requestId`,它用于在 PayZu 内部日志中定位该调用。

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Missing or invalid Bearer token",
  "requestId": "cmp70zh4008dx01s6bwjb5bez"
}
```

| 字段           | 用途                  |
| ------------ | ------------------- |
| `statusCode` | 响应的 HTTP 状态码        |
| `error`      | 错误简称                |
| `message`    | 葡萄牙语错误描述            |
| `requestId`  | 调用的唯一 ID。提交支持工单时请附上 |

## 存放位置 [#存放位置]

| 存放位置                      | 可以吗? |
| ------------------------- | ---- |
| **Google Secret Manager** | 可以   |
| **AWS Secrets Manager**   | 可以   |
| **HashiCorp Vault**       | 可以   |
| **CI 中的环境变量**             | 可以   |
| 生产环境中的 `.env`             | 不可以  |
| 前端(Web、移动端)               | 绝不可以 |

## 支持 [#支持]

<QuickLinks>
  <QuickLink href="https://suporte.payzu.com.br/portal/pt-br/newticket?departmentId=1103699000000006907&layoutId=1103699000000074011" title="提交工单" />

  <QuickLink href="https://suporte.payzu.com.br" title="支持门户" />
</QuickLinks>


# For AIs (LLMs) (/docs/conta-digital/for-ai.en)



<QuickLinks>
  <QuickLink href="https://docs.payzu.com.br/conta-digital/SKILL.md" title="SKILL.md (load into Claude/Cursor)" />

  <QuickLink href="https://docs.payzu.com.br/conta-digital/llms-full.txt" title="llms-full.txt (everything)" />

  <QuickLink href="https://docs.payzu.com.br/openapi/payzu-conta-digital-api.json" title="OpenAPI JSON" />
</QuickLinks>

This documentation was designed to be consumed by both humans and AI assistants. You can copy the content directly into a chat or point the AI to a fixed URL.

## SKILL.md (recommended) [#skillmd-recommended]

[`SKILL.md`](https://docs.payzu.com.br/conta-digital/SKILL.md) is the most compact and up-to-date way to guide an AI about the Conta Digital API. It contains inviolable rules, examples in Node.js + Python, enums, retry policy and common gotchas in \~7 KB.

**Works with:** Claude Code, Claude Desktop, Cursor, GitHub Copilot, Codeium, Continue, ChatGPT, Gemini, and any other tool that accepts markdown as instruction.

```bash
curl -o .claude/skills/payzu-conta-digital/SKILL.md https://docs.payzu.com.br/conta-digital/SKILL.md
```

<CopyAIPrompt />

From there, any question about Pix deposit, withdrawal, TED, internal transfer, webhooks, authentication or error handling comes answered based on the real doc.

## Endpoints for AIs [#endpoints-for-ais]

| URL                                                                                                       | What it has                                                                                  |
| --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [`/conta-digital/llms.txt`](https://docs.payzu.com.br/conta-digital/llms.txt)                             | Markdown-formatted index with link and description of every page **for Conta Digital only**. |
| [`/conta-digital/llms-full.txt`](https://docs.payzu.com.br/conta-digital/llms-full.txt)                   | **All** of Conta Digital concatenated into one file. Fits in the context of most LLMs.       |
| [`/llms.txt`](https://docs.payzu.com.br/llms.txt)                                                         | Global index (all PayZu products together).                                                  |
| [`/llms-full.txt`](https://docs.payzu.com.br/llms-full.txt)                                               | Global dump (all PayZu products together).                                                   |
| [`/openapi/payzu-conta-digital-api.json`](https://docs.payzu.com.br/openapi/payzu-conta-digital-api.json) | OpenAPI 3 specification for Conta Digital. Source-of-truth for endpoints and schemas.        |
| [`/api-scalar-hub`](https://docs.payzu.com.br/api-scalar-hub)                                             | Interactive Scalar rendering of the Conta Digital OpenAPI.                                   |
| [`/api-swagger-hub`](https://docs.payzu.com.br/api-swagger-hub)                                           | Swagger UI rendering of the Conta Digital OpenAPI.                                           |

## Per page [#per-page]

Every doc page has the equivalent content in plain markdown. Replace `/docs/...` with `/llms.mdx/docs/.../content.md`:

| HTML page                                       | Raw markdown                                                        |
| ----------------------------------------------- | ------------------------------------------------------------------- |
| `/docs/conta-digital`                           | `/llms.mdx/docs/conta-digital/content.md`                           |
| `/docs/conta-digital/webhooks`                  | `/llms.mdx/docs/conta-digital/webhooks/content.md`                  |
| `/docs/conta-digital/depositos/createPixCharge` | `/llms.mdx/docs/conta-digital/depositos/createPixCharge/content.md` |

And every doc page has a &#x2A;*"Copy Markdown"** button at the top, which copies straight to the clipboard.

## Use cases [#use-cases]

### Quick question on ChatGPT/Claude [#quick-question-on-chatgptclaude]

Paste the URL `https://docs.payzu.com.br/conta-digital/llms-full.txt` into the conversation and ask:

```text
Here's the PayZu Conta Digital API doc: https://docs.payzu.com.br/conta-digital/llms-full.txt
Show me a Node.js example of creating a Pix charge for R$ 100
and handling the COMPLETED callback.
```

### Cursor / Copilot in the editor [#cursor--copilot-in-the-editor]

Create a `.cursorrules` or `.github/copilot-instructions.md` file in your repo:

```text
You are integrating with the PayZu Conta Digital API.

Inviolable rules:
- Every call uses Bearer token + Content-Type: application/json
- Base URL: https://pix.payzu.io/v1
- Values in reais (BRL), never cents
- Use a unique, deterministic clientReference for idempotência
- Respond to callbacks with 2xx within 5 seconds
- Dedupe callbacks by id + status, not just id

Full reference: https://docs.payzu.com.br/conta-digital/llms-full.txt
OpenAPI: https://docs.payzu.com.br/openapi/payzu-conta-digital-api.json
```

### RAG / vector store [#rag--vector-store]

The `/llms-full.txt` is the ideal input to index the doc in a vector store (Pinecone, Qdrant, Supabase pgvector). Chunk by `## section` and each chunk lands at 500-2000 tokens, good granularity for retrieval.

### Code generation [#code-generation]

To generate an SDK or HTTP client, point the AI to `/openapi/payzu-conta-digital-api.json`:

```text
Generate a typed TypeScript client for this API:
https://docs.payzu.com.br/openapi/payzu-conta-digital-api.json
Use Zod for runtime validation and native fetch.
```

## Updates [#updates]

Every change published to the doc updates automatically:

* `/llms.txt` and `/llms-full.txt` on the next deploy
* `/openapi/payzu-conta-digital-api.json` whenever the API gains new endpoints or schema changes
* The "Copy Markdown" button always serves the rendered version of the current page

<Callout type="info">
  If your AI gives an answer that seems outdated, ask it to re-fetch `https://docs.payzu.com.br/conta-digital/llms-full.txt`. The publication timestamp is at the end of the file.
</Callout>


# Para IAs (LLMs) (/docs/conta-digital/for-ai)



<QuickLinks>
  <QuickLink href="https://docs.payzu.com.br/conta-digital/SKILL.md" title="SKILL.md (carregar no Claude/Cursor)" />

  <QuickLink href="https://docs.payzu.com.br/conta-digital/llms-full.txt" title="llms-full.txt (tudo)" />

  <QuickLink href="https://docs.payzu.com.br/openapi/payzu-conta-digital-api.json" title="OpenAPI JSON" />
</QuickLinks>

Esta documentação foi pensada para ser consumida tanto por humanos quanto por assistentes de IA. Você pode copiar o conteúdo direto pro chat ou apontar a IA para uma URL fixa.

## SKILL.md (recomendado) [#skillmd-recomendado]

[`SKILL.md`](https://docs.payzu.com.br/conta-digital/SKILL.md) é a forma mais compacta e atualizada de orientar uma IA sobre a API Conta Digital. Contém regras invioláveis, exemplos em Node.js + Python, enums, retry policy e pegadinhas comuns em \~7 KB.

**Funciona com:** Claude Code, Claude Desktop, Cursor, GitHub Copilot, Codeium, Continue, ChatGPT, Gemini, e qualquer outro que aceite markdown como instrução.

```bash
curl -o .claude/skills/payzu-conta-digital/SKILL.md https://docs.payzu.com.br/conta-digital/SKILL.md
```

<CopyAIPrompt />

A partir daí, qualquer pergunta sobre depósito Pix, saque, TED, transferência interna, webhooks, autenticação ou tratamento de erros vem respondida com base na doc real.

## Endpoints para IAs [#endpoints-para-ias]

| URL                                                                                                       | O que tem                                                                               |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [`/conta-digital/llms.txt`](https://docs.payzu.com.br/conta-digital/llms.txt)                             | Índice em formato markdown com link e descrição de toda página **só de Conta Digital**. |
| [`/conta-digital/llms-full.txt`](https://docs.payzu.com.br/conta-digital/llms-full.txt)                   | **Toda** Conta Digital concatenada em um arquivo. Cabe no contexto da maioria dos LLMs. |
| [`/llms.txt`](https://docs.payzu.com.br/llms.txt)                                                         | Índice global (todos os produtos PayZu juntos).                                         |
| [`/llms-full.txt`](https://docs.payzu.com.br/llms-full.txt)                                               | Dump global (todos os produtos PayZu juntos).                                           |
| [`/openapi/payzu-conta-digital-api.json`](https://docs.payzu.com.br/openapi/payzu-conta-digital-api.json) | Especificação OpenAPI 3 da Conta Digital. Source-of-truth dos endpoints e schemas.      |
| [`/api-scalar-hub`](https://docs.payzu.com.br/api-scalar-hub)                                             | Renderização Scalar interativa do OpenAPI da Conta Digital.                             |
| [`/api-swagger-hub`](https://docs.payzu.com.br/api-swagger-hub)                                           | Renderização Swagger UI do OpenAPI da Conta Digital.                                    |

## Por página [#por-página]

Toda página da doc tem o conteúdo equivalente em markdown puro. Substitua `/docs/...` por `/llms.mdx/docs/.../content.md`:

| Página HTML                                     | Markdown bruto                                                      |
| ----------------------------------------------- | ------------------------------------------------------------------- |
| `/docs/conta-digital`                           | `/llms.mdx/docs/conta-digital/content.md`                           |
| `/docs/conta-digital/webhooks`                  | `/llms.mdx/docs/conta-digital/webhooks/content.md`                  |
| `/docs/conta-digital/depositos/createPixCharge` | `/llms.mdx/docs/conta-digital/depositos/createPixCharge/content.md` |

E em toda página da doc tem um botão &#x2A;*"Copy Markdown"** no topo, que copia direto pra área de transferência.

## Casos de uso [#casos-de-uso]

### Pergunta rápida no ChatGPT/Claude [#pergunta-rápida-no-chatgptclaude]

Cole a URL `https://docs.payzu.com.br/conta-digital/llms-full.txt` na conversa e pergunte:

```text
Aqui está a doc da API PayZu Conta Digital: https://docs.payzu.com.br/conta-digital/llms-full.txt
Me mostre um exemplo em Node.js de criar uma cobrança Pix de R$ 100
e processar o callback de COMPLETED.
```

### Cursor / Copilot no editor [#cursor--copilot-no-editor]

Crie um arquivo `.cursorrules` ou `.github/copilot-instructions.md` no seu repo:

```text
Você está integrando com a API PayZu Conta Digital.

Regras invioláveis:
- Toda chamada usa Bearer token + Content-Type: application/json
- Base URL: https://pix.payzu.io/v1
- Valores em reais (BRL), nunca centavos
- Use clientReference único e determinístico para idempotência
- Responda callbacks com 2xx em até 5 segundos
- Dedupe callbacks por id + status, não só id

Referência completa: https://docs.payzu.com.br/conta-digital/llms-full.txt
OpenAPI: https://docs.payzu.com.br/openapi/payzu-conta-digital-api.json
```

### RAG / vector store [#rag--vector-store]

O `/llms-full.txt` é o input ideal para indexar a doc em um vector store (Pinecone, Qdrant, Supabase pgvector). Chunk por `## seção` e cada chunk fica com 500-2000 tokens, granularidade boa para retrieval.

### Code generation [#code-generation]

Para gerar SDK ou cliente HTTP, aponte a IA para o `/openapi/payzu-conta-digital-api.json`:

```text
Gere um cliente TypeScript tipado para esta API:
https://docs.payzu.com.br/openapi/payzu-conta-digital-api.json
Use Zod para validação de runtime e fetch nativo.
```

## Atualização [#atualização]

Toda mudança publicada na doc atualiza automaticamente:

* `/llms.txt` e `/llms-full.txt` no próximo deploy
* `/openapi/payzu-conta-digital-api.json` quando a API ganha endpoints novos ou mudanças de schema
* O botão "Copy Markdown" sempre serve a versão renderizada da página atual

<Callout type="info">
  Se sua IA der uma resposta que parece desatualizada, peça pra ela re-buscar `https://docs.payzu.com.br/conta-digital/llms-full.txt`. O timestamp da publicação está no final do arquivo.
</Callout>


# 面向 AI（LLMs） (/docs/conta-digital/for-ai.zh)



<QuickLinks>
  <QuickLink href="https://docs.payzu.com.br/conta-digital/SKILL.md" title="SKILL.md（加载到 Claude/Cursor）" />

  <QuickLink href="https://docs.payzu.com.br/conta-digital/llms-full.txt" title="llms-full.txt（全部）" />

  <QuickLink href="https://docs.payzu.com.br/openapi/payzu-conta-digital-api.json" title="OpenAPI JSON" />
</QuickLinks>

本文档既面向人类，也面向 AI 助手消费。您可以直接将内容复制到聊天中，或将 AI 指向一个固定的 URL。

## SKILL.md（推荐） [#skillmd推荐]

[`SKILL.md`](https://docs.payzu.com.br/conta-digital/SKILL.md) 是引导 AI 使用 Conta Digital API 最紧凑且最新的方式。包含不可违反的规则、Node.js + Python 示例、enums、retry policy 以及常见陷阱，约 7 KB。

**适用于：** Claude Code、Claude Desktop、Cursor、GitHub Copilot、Codeium、Continue、ChatGPT、Gemini，以及任何接受 markdown 作为指令的工具。

```bash
curl -o .claude/skills/payzu-conta-digital/SKILL.md https://docs.payzu.com.br/conta-digital/SKILL.md
```

<CopyAIPrompt />

此后，任何关于 Pix 存款、提现、TED、内部转账、webhooks、认证或错误处理的问题，都会基于真实文档来回答。

## 面向 AI 的端点 [#面向-ai-的端点]

| URL                                                                                                       | 内容                                                          |
| --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [`/conta-digital/llms.txt`](https://docs.payzu.com.br/conta-digital/llms.txt)                             | markdown 格式的索引，包含**仅 Conta Digital** 所有页面的链接和描述。            |
| [`/conta-digital/llms-full.txt`](https://docs.payzu.com.br/conta-digital/llms-full.txt)                   | **全部** Conta Digital 内容合并为一个文件。可放入大多数 LLM 的上下文中。            |
| [`/llms.txt`](https://docs.payzu.com.br/llms.txt)                                                         | 全局索引（所有 PayZu 产品合在一起）。                                      |
| [`/llms-full.txt`](https://docs.payzu.com.br/llms-full.txt)                                               | 全局 dump（所有 PayZu 产品合在一起）。                                   |
| [`/openapi/payzu-conta-digital-api.json`](https://docs.payzu.com.br/openapi/payzu-conta-digital-api.json) | Conta Digital 的 OpenAPI 3 规范。端点和 schemas 的 source-of-truth。 |
| [`/api-scalar-hub`](https://docs.payzu.com.br/api-scalar-hub)                                             | Conta Digital OpenAPI 的 Scalar 交互式渲染。                       |
| [`/api-swagger-hub`](https://docs.payzu.com.br/api-swagger-hub)                                           | Conta Digital OpenAPI 的 Swagger UI 渲染。                      |

## 按页面 [#按页面]

文档的每个页面都有等价的纯 markdown 内容。将 `/docs/...` 替换为 `/llms.mdx/docs/.../content.md`：

| HTML 页面                                         | 原始 markdown                                                         |
| ----------------------------------------------- | ------------------------------------------------------------------- |
| `/docs/conta-digital`                           | `/llms.mdx/docs/conta-digital/content.md`                           |
| `/docs/conta-digital/webhooks`                  | `/llms.mdx/docs/conta-digital/webhooks/content.md`                  |
| `/docs/conta-digital/depositos/createPixCharge` | `/llms.mdx/docs/conta-digital/depositos/createPixCharge/content.md` |

并且文档的每个页面顶部都有一个 &#x2A;*"Copy Markdown"** 按钮，直接复制到剪贴板。

## 使用场景 [#使用场景]

### 在 ChatGPT/Claude 中快速提问 [#在-chatgptclaude-中快速提问]

将 URL `https://docs.payzu.com.br/conta-digital/llms-full.txt` 粘贴到对话中并提问：

```text
这是 PayZu Conta Digital API 的文档：https://docs.payzu.com.br/conta-digital/llms-full.txt
请给我一个 Node.js 示例：创建一笔 R$ 100 的 Pix 收款，
并处理 COMPLETED 的 callback。
```

### 编辑器中的 Cursor / Copilot [#编辑器中的-cursor--copilot]

在您的 repo 中创建一个 `.cursorrules` 或 `.github/copilot-instructions.md` 文件：

```text
您正在与 PayZu Conta Digital API 集成。

不可违反的规则：
- 每次调用使用 Bearer token + Content-Type: application/json
- Base URL: https://pix.payzu.io/v1
- 金额以雷亚尔（BRL）为单位，绝不使用分
- 使用唯一且确定性的 clientReference 来实现 idempotência
- 在 5 秒内以 2xx 响应 callbacks
- 通过 id + status 对 callbacks 进行去重，不要仅按 id

完整参考：https://docs.payzu.com.br/conta-digital/llms-full.txt
OpenAPI: https://docs.payzu.com.br/openapi/payzu-conta-digital-api.json
```

### RAG / vector store [#rag--vector-store]

`/llms-full.txt` 是将文档索引到 vector store（Pinecone、Qdrant、Supabase pgvector）的理想输入。按 `## 章节` 进行 chunk，每个 chunk 为 500-2000 tokens，granularidade 适合 retrieval。

### Code generation [#code-generation]

要生成 SDK 或 HTTP 客户端，将 AI 指向 `/openapi/payzu-conta-digital-api.json`：

```text
为这个 API 生成一个带类型的 TypeScript 客户端：
https://docs.payzu.com.br/openapi/payzu-conta-digital-api.json
使用 Zod 进行运行时验证以及原生 fetch。
```

## 更新 [#更新]

文档发布的每次变更会自动更新：

* `/llms.txt` 和 `/llms-full.txt` 将在下次 deploy 时更新
* `/openapi/payzu-conta-digital-api.json` 在 API 新增端点或 schema 变更时更新
* "Copy Markdown" 按钮始终提供当前页面渲染后的版本

<Callout type="info">
  如果您的 AI 给出的回答看起来已过时，请让它重新获取 `https://docs.payzu.com.br/conta-digital/llms-full.txt`。文件末尾标有发布时间戳。
</Callout>


# Getting started (/docs/conta-digital/getting-started.en)



<QuickLinks>
  <QuickLink href="/docs/conta-digital/authentication" title="Authentication" />

  <QuickLink href="/docs/conta-digital/depositos" title="Deposits" />

  <QuickLink href="/docs/conta-digital/saques" title="Withdrawals" />

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

  <QuickLink href="/docs/conta-digital/glossary" title="Glossary" />
</QuickLinks>

<Mermaid
  chart="`
flowchart LR
  A[&#x22;Create account&#x22;] --> B[&#x22;Validate token&#x22;]
  B --> C[&#x22;Create charge&#x22;]
  C --> D[&#x22;Receive callback&#x22;]

  click A &#x22;https://abrirconta.payzu.com.br&#x22; &#x22;Open PayZu account&#x22;
  click B &#x22;/docs/conta-digital/gestao-de-conta/getUserBalance&#x22; &#x22;GET /user/balance&#x22;
  click C &#x22;/docs/conta-digital/depositos/createPixCharge&#x22; &#x22;POST /pix&#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
`"
/>

<Steps>
  <Step>
    ### Create account [#create-account]

    Open your account at [abrirconta.payzu.com.br](https://abrirconta.payzu.com.br). After approval you receive:

    * **Bearer token**, used in every request. See [Authentication](/docs/conta-digital/authentication).
    * **Base URL**, `https://pix.payzu.io/v1`.

    <Callout type="warn">
      Store the token in a vault (Google Secret Manager, AWS Secrets, etc).
      Never commit it to a repository or expose it on the front-end.
    </Callout>
  </Step>

  <Step>
    ### Validate authentication [#validate-authentication]

    To confirm the token works, check the balance via [`GET /user/balance`](/docs/conta-digital/gestao-de-conta/getUserBalance).

    <Tabs items="['curl', 'Node']">
      <Tab value="curl">
        ```bash
        curl https://pix.payzu.io/v1/user/balance \
          -H "Authorization: Bearer YOUR_TOKEN" \
          -H "Content-Type: application/json"
        ```
      </Tab>

      <Tab value="Node">
        ```js
        const res = await fetch('https://pix.payzu.io/v1/user/balance', {
          headers: {
            Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
            'Content-Type': 'application/json',
          },
        });
        const balance = await res.json();
        ```
      </Tab>
    </Tabs>

    If you get back a JSON with the balance, you're authenticated. If it returns `401`, double-check the token. See [HTTP codes in the glossary](/docs/conta-digital/glossary#códigos-http).
  </Step>

  <Step>
    ### Create the first Pix charge [#create-the-first-pix-charge]

    Create a charge via [`POST /pix`](/docs/conta-digital/depositos/createPixCharge). Full schema in the reference.

    <Tabs items="['curl', 'Node']">
      <Tab value="curl">
        ```bash
        curl -X POST https://pix.payzu.io/v1/pix \
          -H "Authorization: Bearer YOUR_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{
            "amount": 10.90,
            "generatedName": "João da Silva",
            "generatedDocument": "12345678909",
            "callbackUrl": "https://yoursite.com/webhooks/payzu",
            "clientReference": "order-2025-001"
          }'
        ```
      </Tab>

      <Tab value="Node">
        ```js
        const res = await fetch('https://pix.payzu.io/v1/pix', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            amount: 10.90,
            generatedName: 'João da Silva',
            generatedDocument: '12345678909',
            callbackUrl: 'https://yoursite.com/webhooks/payzu',
            clientReference: 'order-2025-001',
          }),
        });
        const charge = await res.json();
        ```
      </Tab>
    </Tabs>

    The response contains `qrCodeText` (copy-and-paste), `qrCodeUrl` and the transaction `id`.

    <Callout type="info">
      Amounts are always in &#x2A;*reais (BRL)**, not cents. `10.90` is R$ 10.90.
    </Callout>
  </Step>

  <Step>
    ### Receive the callback [#receive-the-callback]

    When the payer completes the Pix, PayZu sends a `POST` to the `callbackUrl` you provided with the updated transaction (`status: "COMPLETED"`). Respond with `2xx` within 5 seconds.

    ```http
    POST /webhooks/payzu
    Content-Type: application/json

    {
      "id": "PZ_xxx",
      "status": "COMPLETED",
      "amount": 10.90,
      "clientReference": "order-2025-001",
      "endToEndId": "E18236120202511231046s1235ee7",
      "paidAt": "2026-05-21T10:46:26.986Z"
    }
    ```

    Retry details, full payload and security in [Webhooks](/docs/conta-digital/webhooks).
  </Step>
</Steps>

## Next steps [#next-steps]

<QuickLinks>
  <QuickLink href="/docs/conta-digital/saques" title="Make a withdrawal" />

  <QuickLink href="/docs/conta-digital/gestao-de-conta" title="Check statement" />

  <QuickLink href="/api-scalar-hub" title="Try it on Scalar" />
</QuickLinks>


# Primeiros passos (/docs/conta-digital/getting-started)



<QuickLinks>
  <QuickLink href="/docs/conta-digital/authentication" title="Autenticação" />

  <QuickLink href="/docs/conta-digital/depositos" title="Depósitos" />

  <QuickLink href="/docs/conta-digital/saques" title="Saques" />

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

  <QuickLink href="/docs/conta-digital/glossary" title="Glossário" />
</QuickLinks>

<Mermaid
  chart="`
flowchart LR
  A[&#x22;Criar conta&#x22;] --> B[&#x22;Validar token&#x22;]
  B --> C[&#x22;Criar cobrança&#x22;]
  C --> D[&#x22;Receber callback&#x22;]

  click A &#x22;https://abrirconta.payzu.com.br&#x22; &#x22;Abrir conta PayZu&#x22;
  click B &#x22;/docs/conta-digital/gestao-de-conta/getUserBalance&#x22; &#x22;GET /user/balance&#x22;
  click C &#x22;/docs/conta-digital/depositos/createPixCharge&#x22; &#x22;POST /pix&#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
`"
/>

<Steps>
  <Step>
    ### Criar conta [#criar-conta]

    Abra sua conta em [abrirconta.payzu.com.br](https://abrirconta.payzu.com.br). Após aprovação você recebe:

    * **Bearer token**, usado em todas as requisições. Ver [Autenticação](/docs/conta-digital/authentication).
    * **Base URL**, `https://pix.payzu.io/v1`.

    <Callout type="warn">
      Guarde o token em vault (Google Secret Manager, AWS Secrets, etc).
      Nunca commite em repositório nem exponha no front-end.
    </Callout>
  </Step>

  <Step>
    ### Validar autenticação [#validar-autenticação]

    Para confirmar que o token funciona, consulte o saldo via [`GET /user/balance`](/docs/conta-digital/gestao-de-conta/getUserBalance).

    <Tabs items="['curl', 'Node']">
      <Tab value="curl">
        ```bash
        curl https://pix.payzu.io/v1/user/balance \
          -H "Authorization: Bearer SEU_TOKEN" \
          -H "Content-Type: application/json"
        ```
      </Tab>

      <Tab value="Node">
        ```js
        const res = await fetch('https://pix.payzu.io/v1/user/balance', {
          headers: {
            Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
            'Content-Type': 'application/json',
          },
        });
        const balance = await res.json();
        ```
      </Tab>
    </Tabs>

    Se voltar o JSON com o saldo, está autenticado. Se retornar `401`, revise o token. Ver [códigos HTTP no glossário](/docs/conta-digital/glossary#códigos-http).
  </Step>

  <Step>
    ### Criar a primeira cobrança Pix [#criar-a-primeira-cobrança-pix]

    Crie uma cobrança via [`POST /pix`](/docs/conta-digital/depositos/createPixCharge). Schema completo na referência.

    <Tabs items="['curl', 'Node']">
      <Tab value="curl">
        ```bash
        curl -X POST https://pix.payzu.io/v1/pix \
          -H "Authorization: Bearer SEU_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{
            "amount": 10.90,
            "generatedName": "João da Silva",
            "generatedDocument": "12345678909",
            "callbackUrl": "https://seusite.com.br/webhooks/payzu",
            "clientReference": "pedido-2025-001"
          }'
        ```
      </Tab>

      <Tab value="Node">
        ```js
        const res = await fetch('https://pix.payzu.io/v1/pix', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            amount: 10.90,
            generatedName: 'João da Silva',
            generatedDocument: '12345678909',
            callbackUrl: 'https://seusite.com.br/webhooks/payzu',
            clientReference: 'pedido-2025-001',
          }),
        });
        const charge = await res.json();
        ```
      </Tab>
    </Tabs>

    A resposta traz `qrCodeText` (copia-e-cola), `qrCodeUrl` e o `id` da transação.

    <Callout type="info">
      Valores estão sempre em &#x2A;*reais (BRL)**, não em centavos. `10.90` é R$ 10,90.
    </Callout>
  </Step>

  <Step>
    ### Receber o callback [#receber-o-callback]

    Quando o pagador concluir o Pix, a PayZu envia um `POST` para a `callbackUrl` informada com a transação atualizada (`status: "COMPLETED"`). Responda com `2xx` em até 5 segundos.

    ```http
    POST /webhooks/payzu
    Content-Type: application/json

    {
      "id": "PZ_xxx",
      "status": "COMPLETED",
      "amount": 10.90,
      "clientReference": "pedido-2025-001",
      "endToEndId": "E18236120202511231046s1235ee7",
      "paidAt": "2026-05-21T10:46:26.986Z"
    }
    ```

    Detalhes de retry, payload completo e segurança em [Webhooks](/docs/conta-digital/webhooks).
  </Step>
</Steps>

## Próximos passos [#próximos-passos]

<QuickLinks>
  <QuickLink href="/docs/conta-digital/saques" title="Fazer um saque" />

  <QuickLink href="/docs/conta-digital/gestao-de-conta" title="Consultar extrato" />

  <QuickLink href="/api-scalar-hub" title="Try-it no Scalar" />
</QuickLinks>


# 快速入门 (/docs/conta-digital/getting-started.zh)



<QuickLinks>
  <QuickLink href="/docs/conta-digital/authentication" title="身份认证" />

  <QuickLink href="/docs/conta-digital/depositos" title="收款" />

  <QuickLink href="/docs/conta-digital/saques" title="付款" />

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

  <QuickLink href="/docs/conta-digital/glossary" title="术语表" />
</QuickLinks>

<Mermaid
  chart="`
flowchart LR
  A[&#x22;创建账户&#x22;] --> B[&#x22;验证 token&#x22;]
  B --> C[&#x22;创建收款&#x22;]
  C --> D[&#x22;接收 callback&#x22;]

  click A &#x22;https://abrirconta.payzu.com.br&#x22; &#x22;开通 PayZu 账户&#x22;
  click B &#x22;/docs/conta-digital/gestao-de-conta/getUserBalance&#x22; &#x22;GET /user/balance&#x22;
  click C &#x22;/docs/conta-digital/depositos/createPixCharge&#x22; &#x22;POST /pix&#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
`"
/>

<Steps>
  <Step>
    ### 创建账户 [#创建账户]

    请在 [abrirconta.payzu.com.br](https://abrirconta.payzu.com.br) 开通账户。审核通过后,您将获得:

    * **Bearer token**,用于所有请求。详见 [身份认证](/docs/conta-digital/authentication)。
    * **Base URL**,`https://pix.payzu.io/v1`。

    <Callout type="warn">
      请将 token 保存在 vault 中(Google Secret Manager、AWS Secrets 等)。
      切勿提交到代码仓库,也不要在前端暴露。
    </Callout>
  </Step>

  <Step>
    ### 验证身份认证 [#验证身份认证]

    要确认 token 是否生效,可通过 [`GET /user/balance`](/docs/conta-digital/gestao-de-conta/getUserBalance) 查询余额。

    <Tabs items="['curl', 'Node']">
      <Tab value="curl">
        ```bash
        curl https://pix.payzu.io/v1/user/balance \
          -H "Authorization: Bearer SEU_TOKEN" \
          -H "Content-Type: application/json"
        ```
      </Tab>

      <Tab value="Node">
        ```js
        const res = await fetch('https://pix.payzu.io/v1/user/balance', {
          headers: {
            Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
            'Content-Type': 'application/json',
          },
        });
        const balance = await res.json();
        ```
      </Tab>
    </Tabs>

    如果返回包含余额的 JSON,则表示认证成功。若返回 `401`,请检查 token。详见 [术语表中的 HTTP 状态码](/docs/conta-digital/glossary#códigos-http)。
  </Step>

  <Step>
    ### 创建首笔 Pix 收款 [#创建首笔-pix-收款]

    通过 [`POST /pix`](/docs/conta-digital/depositos/createPixCharge) 创建收款。完整 schema 见参考文档。

    <Tabs items="['curl', 'Node']">
      <Tab value="curl">
        ```bash
        curl -X POST https://pix.payzu.io/v1/pix \
          -H "Authorization: Bearer SEU_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{
            "amount": 10.90,
            "generatedName": "João da Silva",
            "generatedDocument": "12345678909",
            "callbackUrl": "https://seusite.com.br/webhooks/payzu",
            "clientReference": "pedido-2025-001"
          }'
        ```
      </Tab>

      <Tab value="Node">
        ```js
        const res = await fetch('https://pix.payzu.io/v1/pix', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            amount: 10.90,
            generatedName: 'João da Silva',
            generatedDocument: '12345678909',
            callbackUrl: 'https://seusite.com.br/webhooks/payzu',
            clientReference: 'pedido-2025-001',
          }),
        });
        const charge = await res.json();
        ```
      </Tab>
    </Tabs>

    响应包含 `qrCodeText`(复制粘贴码)、`qrCodeUrl` 以及交易 `id`。

    <Callout type="info">
      金额始终以 &#x2A;*雷亚尔(BRL)** 为单位,而非以分计。`10.90` 表示 R$ 10,90。
    </Callout>
  </Step>

  <Step>
    ### 接收 callback [#接收-callback]

    当付款方完成 Pix 支付后,PayZu 会向指定的 `callbackUrl` 发送 `POST` 请求,附带更新后的交易信息(`status: "COMPLETED"`)。请在 5 秒内返回 `2xx`。

    ```http
    POST /webhooks/payzu
    Content-Type: application/json

    {
      "id": "PZ_xxx",
      "status": "COMPLETED",
      "amount": 10.90,
      "clientReference": "pedido-2025-001",
      "endToEndId": "E18236120202511231046s1235ee7",
      "paidAt": "2026-05-21T10:46:26.986Z"
    }
    ```

    重试机制、完整 payload 及安全相关详情见 [Webhooks](/docs/conta-digital/webhooks)。
  </Step>
</Steps>

## 后续步骤 [#后续步骤]

<QuickLinks>
  <QuickLink href="/docs/conta-digital/saques" title="发起一笔付款" />

  <QuickLink href="/docs/conta-digital/gestao-de-conta" title="查询账户明细" />

  <QuickLink href="/api-scalar-hub" title="在 Scalar 中试用" />
</QuickLinks>


# Glossary (/docs/conta-digital/glossary.en)



<QuickLinks>
  <QuickLink href="/docs/conta-digital/depositos" title="Deposits" />

  <QuickLink href="/docs/conta-digital/saques" title="Withdrawals" />

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

  <QuickLink href="/docs/conta-digital/authentication" title="Authentication" />
</QuickLinks>

## Transaction status (`status`) [#transaction-status-status]

| Status      | Description                                             |
| ----------- | ------------------------------------------------------- |
| `PENDING`   | Transaction created, awaiting payment or processing     |
| `COMPLETED` | Transaction completed successfully                      |
| `CANCELED`  | Transaction canceled (error or manual request)          |
| `REFUNDED`  | Amount refunded to the payer                            |
| `EXPIRED`   | Payment deadline expired, transaction was not completed |

## Transaction types (`type`) [#transaction-types-type]

| Value      | What it is                               |
| ---------- | ---------------------------------------- |
| `DEPOSIT`  | Money in (Pix in, refund received)       |
| `WITHDRAW` | Money out (Pix, TED, QR, data, internal) |

## Pix key types (`pixType`) [#pix-key-types-pixtype]

| Type    | Description                                 | Format                                 |
| ------- | ------------------------------------------- | -------------------------------------- |
| `cpf`   | 11 numeric digits, no formatting            | `12345678901`                          |
| `cnpj`  | 14 numeric digits, no formatting            | `12345678901234`                       |
| `phone` | International format with country code (55) | `5511987654321`                        |
| `email` | Valid email address                         | `usuario@dominio.com.br`               |
| `evp`   | UUID generated by the Central Bank          | `123e4567-e89b-12d3-a456-426655440000` |

## Infractions (MED) [#infractions-med]

### Fields of the `infraction` object [#fields-of-the-infraction-object]

| Field                   | Type               | Description                                |
| ----------------------- | ------------------ | ------------------------------------------ |
| `id`                    | string             | Unique identifier of the infraction        |
| `protocol`              | string             | Protocol of the infraction record          |
| `type`                  | `InfractionType`   | Infraction type                            |
| `status`                | `InfractionStatus` | Current status                             |
| `reportedBy`            | `ReportedType`     | Origin of the report                       |
| `reportDetails`         | string             | Report details                             |
| `analysisResult`        | `AnalysisResult`   | Analysis result (`null` while pending)     |
| `analysisDetails`       | string \| null     | Analysis details                           |
| `transactionEndToEndId` | string             | EndToEnd ID of the related Pix transaction |
| `transactionId`         | string             | Transaction ID in the PayZu system         |
| `creationDate`          | string             | When the record was created                |
| `lastModificationDate`  | string             | Last update                                |
| `dueDate`               | string \| null     | Deadline for analysis                      |

### `InfractionType` [#infractiontype]

| Value              | Description                                            |
| ------------------ | ------------------------------------------------------ |
| `REFUND_REQUEST`   | Request to refund amounts from a Pix transaction       |
| `FRAUD`            | Transaction related to fraudulent activity             |
| `REFUND_CANCELLED` | Cancellation of a previously registered refund request |

### `ReportedType` [#reportedtype]

| Value                  | Description                                                           |
| ---------------------- | --------------------------------------------------------------------- |
| `DEBITED_PARTICIPANT`  | The party who sent the funds (payer) registered the infraction        |
| `CREDITED_PARTICIPANT` | The party who received the funds (receiver) registered the infraction |

### `AnalysisResult` [#analysisresult]

| Value       | Description                                   |
| ----------- | --------------------------------------------- |
| `AGREED`    | Infraction is valid, refund will be processed |
| `DISAGREED` | Infraction is not valid, no refund            |

## HTTP codes [#http-codes]

| Code  | What it means                                      |
| ----- | -------------------------------------------------- |
| `200` | Success                                            |
| `201` | Resource created                                   |
| `400` | Invalid payload                                    |
| `401` | Missing, invalid, or revoked token                 |
| `403` | Valid token but no permission                      |
| `404` | Resource not found                                 |
| `409` | Conflict (idempotência, resource in invalid state) |
| `422` | Semantic validation failed                         |
| `429` | Rate limit reached                                 |
| `5xx` | PayZu server error (retry with backoff)            |

## Common fields [#common-fields]

| Field             | Type   | Description                                                          |
| ----------------- | ------ | -------------------------------------------------------------------- |
| `id`              | string | Unique identifier of the transaction at PayZu                        |
| `clientReference` | string | External identifier you provide, returned on every callback          |
| `amount`          | number | Value in &#x2A;*reais (BRL)**, never cents                           |
| `callbackUrl`     | string | URL to receive webhooks on status changes                            |
| `endToEndId`      | string | Pix EndToEnd ID (Bacen). Format `E` + 32 chars                       |
| `requestId`       | string | Unique ID of the PayZu call. Appears on every error, send to support |


# Glossário (/docs/conta-digital/glossary)



<QuickLinks>
  <QuickLink href="/docs/conta-digital/depositos" title="Depósitos" />

  <QuickLink href="/docs/conta-digital/saques" title="Saques" />

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

  <QuickLink href="/docs/conta-digital/authentication" title="Autenticação" />
</QuickLinks>

## Status de transação (`status`) [#status-de-transação-status]

| Status      | Descrição                                               |
| ----------- | ------------------------------------------------------- |
| `PENDING`   | Transação criada, aguardando pagamento ou processamento |
| `COMPLETED` | Transação concluída com sucesso                         |
| `CANCELED`  | Transação cancelada (erro ou solicitação manual)        |
| `REFUNDED`  | Valor reembolsado ao pagador                            |
| `EXPIRED`   | Prazo de pagamento expirou, transação não foi concluída |

## Tipos de transação (`type`) [#tipos-de-transação-type]

| Valor      | O que é                                          |
| ---------- | ------------------------------------------------ |
| `DEPOSIT`  | Entrada de dinheiro (Pix in, estorno recebido)   |
| `WITHDRAW` | Saída de dinheiro (Pix, TED, QR, dados, interna) |

## Tipos de chave Pix (`pixType`) [#tipos-de-chave-pix-pixtype]

| Tipo    | Descrição                           | Formato                                |
| ------- | ----------------------------------- | -------------------------------------- |
| `cpf`   | 11 dígitos numéricos sem formatação | `12345678901`                          |
| `cnpj`  | 14 dígitos numéricos sem formatação | `12345678901234`                       |
| `phone` | Formato internacional com DDI (55)  | `5511987654321`                        |
| `email` | Endereço de email válido            | `usuario@dominio.com.br`               |
| `evp`   | UUID gerado pelo Banco Central      | `123e4567-e89b-12d3-a456-426655440000` |

## Infrações (MED) [#infrações-med]

### Campos do objeto `infraction` [#campos-do-objeto-infraction]

| Campo                   | Tipo               | Descrição                                       |
| ----------------------- | ------------------ | ----------------------------------------------- |
| `id`                    | string             | Identificador único da infração                 |
| `protocol`              | string             | Protocolo do registro da infração               |
| `type`                  | `InfractionType`   | Tipo de infração                                |
| `status`                | `InfractionStatus` | Status atual                                    |
| `reportedBy`            | `ReportedType`     | Origem da denúncia                              |
| `reportDetails`         | string             | Detalhes da denúncia                            |
| `analysisResult`        | `AnalysisResult`   | Resultado da análise (`null` enquanto pendente) |
| `analysisDetails`       | string \| null     | Detalhes da análise                             |
| `transactionEndToEndId` | string             | EndToEnd ID da transação Pix relacionada        |
| `transactionId`         | string             | ID da transação no sistema PayZu                |
| `creationDate`          | string             | Quando o registro foi criado                    |
| `lastModificationDate`  | string             | Última atualização                              |
| `dueDate`               | string \| null     | Prazo limite para análise                       |

### `InfractionType` [#infractiontype]

| Valor              | Descrição                                                           |
| ------------------ | ------------------------------------------------------------------- |
| `REFUND_REQUEST`   | Solicitação de devolução de valores de uma transação Pix            |
| `FRAUD`            | Transação relacionada a atividade fraudulenta                       |
| `REFUND_CANCELLED` | Cancelamento de uma solicitação de devolução previamente registrada |

### `ReportedType` [#reportedtype]

| Valor                  | Descrição                                                 |
| ---------------------- | --------------------------------------------------------- |
| `DEBITED_PARTICIPANT`  | Quem enviou os recursos (pagador) registrou a infração    |
| `CREDITED_PARTICIPANT` | Quem recebeu os recursos (recebedor) registrou a infração |

### `AnalysisResult` [#analysisresult]

| Valor       | Descrição                                   |
| ----------- | ------------------------------------------- |
| `AGREED`    | Infração procede, devolução será processada |
| `DISAGREED` | Infração não procede, sem devolução         |

## Códigos HTTP [#códigos-http]

| Código | O que significa                                     |
| ------ | --------------------------------------------------- |
| `200`  | Sucesso                                             |
| `201`  | Recurso criado                                      |
| `400`  | Payload inválido                                    |
| `401`  | Token ausente, inválido ou revogado                 |
| `403`  | Token válido mas sem permissão                      |
| `404`  | Recurso não encontrado                              |
| `409`  | Conflito (idempotência, recurso em estado inválido) |
| `422`  | Validação semântica falhou                          |
| `429`  | Rate limit atingido                                 |
| `5xx`  | Erro do servidor PayZu (retry com backoff)          |

## Campos comuns [#campos-comuns]

| Campo             | Tipo   | Descrição                                                         |
| ----------------- | ------ | ----------------------------------------------------------------- |
| `id`              | string | Identificador único da transação na PayZu                         |
| `clientReference` | string | Identificador externo que você passa, volta em todo callback      |
| `amount`          | number | Valor em &#x2A;*reais (BRL)**, nunca centavos                     |
| `callbackUrl`     | string | URL pra receber webhooks de mudança de status                     |
| `endToEndId`      | string | EndToEnd ID do Pix (Bacen). Formato `E` + 32 chars                |
| `requestId`       | string | ID único da chamada PayZu. Aparece em todo erro, envie ao suporte |


# 术语表 (/docs/conta-digital/glossary.zh)



<QuickLinks>
  <QuickLink href="/docs/conta-digital/depositos" title="存款" />

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

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

  <QuickLink href="/docs/conta-digital/authentication" title="Autenticação" />
</QuickLinks>

## 交易状态 (`status`) [#交易状态-status]

| Status      | 说明             |
| ----------- | -------------- |
| `PENDING`   | 交易已创建，等待支付或处理  |
| `COMPLETED` | 交易成功完成         |
| `CANCELED`  | 交易已取消（出错或手动请求） |
| `REFUNDED`  | 金额已退还给付款方      |
| `EXPIRED`   | 支付期限已过，交易未完成   |

## 交易类型 (`type`) [#交易类型-type]

| 值          | 含义                         |
| ---------- | -------------------------- |
| `DEPOSIT`  | 资金流入（Pix in、收到的退款）         |
| `WITHDRAW` | 资金流出（Pix、TED、QR、银行数据、内部转账） |

## Pix 密钥类型 (`pixType`) [#pix-密钥类型-pixtype]

| 类型      | 说明               | 格式                                     |
| ------- | ---------------- | -------------------------------------- |
| `cpf`   | 11 位纯数字，无格式化     | `12345678901`                          |
| `cnpj`  | 14 位纯数字，无格式化     | `12345678901234`                       |
| `phone` | 含国际区号 (55) 的国际格式 | `5511987654321`                        |
| `email` | 有效的电子邮箱地址        | `usuario@dominio.com.br`               |
| `evp`   | 由 Bacen 生成的 UUID | `123e4567-e89b-12d3-a456-426655440000` |

## 违规处理 (MED) [#违规处理-med]

### `infraction` 对象字段 [#infraction-对象字段]

| 字段                      | 类型                 | 说明                     |
| ----------------------- | ------------------ | ---------------------- |
| `id`                    | string             | 违规记录的唯一标识符             |
| `protocol`              | string             | 违规登记协议号                |
| `type`                  | `InfractionType`   | 违规类型                   |
| `status`                | `InfractionStatus` | 当前状态                   |
| `reportedBy`            | `ReportedType`     | 举报来源                   |
| `reportDetails`         | string             | 举报详情                   |
| `analysisResult`        | `AnalysisResult`   | 分析结果（待处理时为 `null`）     |
| `analysisDetails`       | string \| null     | 分析详情                   |
| `transactionEndToEndId` | string             | 相关 Pix 交易的 EndToEnd ID |
| `transactionId`         | string             | 该交易在 PayZu 系统中的 ID     |
| `creationDate`          | string             | 记录创建时间                 |
| `lastModificationDate`  | string             | 最近更新时间                 |
| `dueDate`               | string \| null     | 分析截止期限                 |

### `InfractionType` [#infractiontype]

| 值                  | 说明               |
| ------------------ | ---------------- |
| `REFUND_REQUEST`   | 请求退还某笔 Pix 交易的金额 |
| `FRAUD`            | 与欺诈活动相关的交易       |
| `REFUND_CANCELLED` | 取消已登记的退款请求       |

### `ReportedType` [#reportedtype]

| 值                      | 说明                |
| ---------------------- | ----------------- |
| `DEBITED_PARTICIPANT`  | 发送资金的一方（付款方）登记了违规 |
| `CREDITED_PARTICIPANT` | 接收资金的一方（收款方）登记了违规 |

### `AnalysisResult` [#analysisresult]

| 值           | 说明         |
| ----------- | ---------- |
| `AGREED`    | 违规成立，将处理退款 |
| `DISAGREED` | 违规不成立，不予退款 |

## HTTP 状态码 [#http-状态码]

| 代码    | 含义                        |
| ----- | ------------------------- |
| `200` | 成功                        |
| `201` | 资源已创建                     |
| `400` | payload 无效                |
| `401` | Bearer token 缺失、无效或已吊销    |
| `403` | Bearer token 有效但无权限       |
| `404` | 资源未找到                     |
| `409` | 冲突（idempotência、资源处于无效状态） |
| `422` | 语义校验失败                    |
| `429` | 达到速率限制                    |
| `5xx` | PayZu 服务器错误（请使用退避策略重试）    |

## 通用字段 [#通用字段]

| 字段                | 类型     | 说明                                         |
| ----------------- | ------ | ------------------------------------------ |
| `id`              | string | 该交易在 PayZu 中的唯一标识符                         |
| `clientReference` | string | 你传入的外部标识符，将在每次 callback 中返回                |
| `amount`          | number | 金额单位为 &#x2A;*雷亚尔 (BRL)**，绝非分               |
| `callbackUrl`     | string | 用于接收状态变更 webhook 的 URL                     |
| `endToEndId`      | string | Pix 的 EndToEnd ID (Bacen)。格式为 `E` + 32 个字符 |
| `requestId`       | string | PayZu 调用的唯一 ID。出现在所有错误中，请提交给技术支持           |


# Digital Account (/docs/conta-digital/index.en)



The **PayZu Digital Account API** is a **bank account via API**. You operate balance, receive Pix, send Pix and TED, transfer between PayZu accounts, generate statements, query profile and use credit card — all in real time, 24/7. Ideal for personal wallets, business accounts, ERPs and platforms that need banking-as-a-service.

<QuickLinks>
  <QuickLink href="/docs/conta-digital/getting-started" title="Getting started" />

  <QuickLink href="/docs/conta-digital/authentication" title="Authentication" />

  <QuickLink href="/docs/conta-digital/depositos" title="Deposits" />

  <QuickLink href="/docs/conta-digital/saques" title="Withdrawals" />

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

  <QuickLink href="/docs/conta-digital/glossary" title="Glossary" />
</QuickLinks>

<Mermaid
  chart="`
flowchart LR
  Sua[&#x22;Your application&#x22;] <--> API[&#x22;Digital Account API&#x22;]
  API --> D[&#x22;Deposits&#x22;]
  API --> S[&#x22;Withdrawals&#x22;]
  API --> G[&#x22;Account Management&#x22;]
  API --> CB[&#x22;Webhooks&#x22;]

  click D &#x22;/docs/conta-digital/depositos&#x22; &#x22;Deposit endpoints&#x22;
  click S &#x22;/docs/conta-digital/saques&#x22; &#x22;Withdrawal endpoints&#x22;
  click G &#x22;/docs/conta-digital/gestao-de-conta&#x22; &#x22;Management endpoints&#x22;
  click CB &#x22;/docs/conta-digital/webhooks&#x22; &#x22;Webhooks&#x22;

  style API fill:#14ce71,stroke:#0eb464,color:#ffffff
`"
/>

## Where to start [#where-to-start]

| If you are                            | Start with                                                                                                    |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **First integration**                 | [Getting started](/docs/conta-digital/getting-started) → [Authentication](/docs/conta-digital/authentication) |
| **Going straight to reference**       | [Deposits](/docs/conta-digital/depositos), [Withdrawals](/docs/conta-digital/saques)                          |
| **Need to understand callbacks**      | [Webhooks](/docs/conta-digital/webhooks)                                                                      |
| **Reconciling balance and statement** | [Account Management](/docs/conta-digital/gestao-de-conta)                                                     |

## What the API covers [#what-the-api-covers]

| Group                                                     | Endpoints | Typical use                                                |
| --------------------------------------------------------- | --------- | ---------------------------------------------------------- |
| [Deposits](/docs/conta-digital/depositos)                 | 4         | Receive payments via dynamic Pix, generate receipt, refund |
| [Withdrawals](/docs/conta-digital/saques)                 | 6         | Pix (key/QR/data), TED, internal transfer                  |
| [Account Management](/docs/conta-digital/gestao-de-conta) | 4         | Balance, profile, statement, performance summary           |

## Features [#features]

| Aspect         | Value                                   |
| -------------- | --------------------------------------- |
| Endpoints      | **13** grouped in 3 areas               |
| Authentication | Bearer token                            |
| Content-Type   | `application/json` (required)           |
| Amounts        | In reais (BRL), never cents             |
| Webhooks       | Exponential retry up to **72 attempts** |
| Availability   | 24/7, Pix processing in seconds         |

## Environment [#environment]

| Item         | Value                                              |
| ------------ | -------------------------------------------------- |
| **Base URL** | `https://pix.payzu.io/v1`                          |
| **Status**   | [status.payzu.com.br](https://status.payzu.com.br) |

## Digital Account vs Pix Processamento [#digital-account-vs-pix-processamento]

| Aspect    | Digital Account                              | [Pix Processamento](/docs/pix-processamento) |
| --------- | -------------------------------------------- | -------------------------------------------- |
| Focus     | Full bank account (Pix, TED, card, transfer) | High volume of pure Pix                      |
| Outputs   | Pix, TED, QR, bank data                      | Only Pix                                     |
| Base URL  | `https://pix.payzu.io/v1`                    | `https://api.payzu.processamento.com/v1`     |
| Endpoints | 13                                           | 29                                           |
| Ideal for | Wallet, ERP, banking-as-a-service            | Marketplace, gateway, payouts                |

## View the specification [#view-the-specification]

<QuickLinks>
  <QuickLink href="/api-scalar-hub" title="Scalar" />

  <QuickLink href="/api-swagger-hub" title="Swagger UI" />

  <QuickLink href="/openapi/payzu-conta-digital-api.json" title="OpenAPI JSON" />
</QuickLinks>

## Other PayZu products [#other-payzu-products]

<QuickLinks>
  <QuickLink href="/docs/pix-processamento" title="Pix Processamento" />

  <QuickLink href="/docs" title="All products" />
</QuickLinks>

## Need help? [#need-help]

<QuickLinks>
  <QuickLink href="https://suporte.payzu.com.br" title="Support portal" />

  <QuickLink href="https://suporte.payzu.com.br/portal/pt-br/kb/payzu" title="Knowledge base" />

  <QuickLink href="https://suporte.payzu.com.br/portal/pt-br/newticket?departmentId=1103699000000006907&layoutId=1103699000000074011" title="Open ticket" />
</QuickLinks>


# Conta Digital (/docs/conta-digital)



A **API Conta Digital PayZu** é uma **conta bancária via API**. Você opera saldo, recebe Pix, envia Pix e TED, transfere entre contas PayZu, gera extrato, consulta perfil e usa cartão de crédito, tudo em tempo real, 24/7. Ideal para carteiras pessoais, contas empresariais, ERPs e plataformas que precisam de banking-as-a-service.

<QuickLinks>
  <QuickLink href="/docs/conta-digital/getting-started" title="Primeiros passos" />

  <QuickLink href="/docs/conta-digital/authentication" title="Autenticação" />

  <QuickLink href="/docs/conta-digital/depositos" title="Depósitos" />

  <QuickLink href="/docs/conta-digital/saques" title="Saques" />

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

  <QuickLink href="/docs/conta-digital/glossary" title="Glossário" />
</QuickLinks>

<Mermaid
  chart="`
flowchart LR
  Sua[&#x22;Sua aplicação&#x22;] <--> API[&#x22;API Conta Digital&#x22;]
  API --> D[&#x22;Depósitos&#x22;]
  API --> S[&#x22;Saques&#x22;]
  API --> G[&#x22;Gestão de Conta&#x22;]
  API --> CB[&#x22;Webhooks&#x22;]

  click D &#x22;/docs/conta-digital/depositos&#x22; &#x22;Endpoints de depósito&#x22;
  click S &#x22;/docs/conta-digital/saques&#x22; &#x22;Endpoints de saque&#x22;
  click G &#x22;/docs/conta-digital/gestao-de-conta&#x22; &#x22;Endpoints de gestão&#x22;
  click CB &#x22;/docs/conta-digital/webhooks&#x22; &#x22;Webhooks&#x22;

  style API fill:#14ce71,stroke:#0eb464,color:#ffffff
`"
/>

## Por onde começar [#por-onde-começar]

| Se você é                       | Comece por                                                                                                   |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Primeira integração**         | [Primeiros passos](/docs/conta-digital/getting-started) → [Autenticação](/docs/conta-digital/authentication) |
| **Indo direto à referência**    | [Depósitos](/docs/conta-digital/depositos), [Saques](/docs/conta-digital/saques)                             |
| **Precisa entender callbacks**  | [Webhooks](/docs/conta-digital/webhooks)                                                                     |
| **Conciliando saldo e extrato** | [Gestão de Conta](/docs/conta-digital/gestao-de-conta)                                                       |

## O que a API cobre [#o-que-a-api-cobre]

| Grupo                                                  | Endpoints | Uso típico                                                       |
| ------------------------------------------------------ | --------- | ---------------------------------------------------------------- |
| [Depósitos](/docs/conta-digital/depositos)             | 4         | Receber pagamentos via Pix dinâmico, gerar comprovante, estornar |
| [Saques](/docs/conta-digital/saques)                   | 6         | Pix (chave/QR/dados), TED, transferência interna                 |
| [Gestão de Conta](/docs/conta-digital/gestao-de-conta) | 4         | Saldo, perfil, extrato, resumo de performance                    |

## Características [#características]

| Aspecto         | Valor                                   |
| --------------- | --------------------------------------- |
| Endpoints       | **13** agrupados em 3 áreas             |
| Autenticação    | Bearer token                            |
| Content-Type    | `application/json` (obrigatório)        |
| Valores         | Em reais (BRL), nunca centavos          |
| Webhooks        | Retry exponencial até **72 tentativas** |
| Disponibilidade | 24/7, processamento Pix em segundos     |

## Ambiente [#ambiente]

| Item         | Valor                                              |
| ------------ | -------------------------------------------------- |
| **Base URL** | `https://pix.payzu.io/v1`                          |
| **Status**   | [status.payzu.com.br](https://status.payzu.com.br) |

## Conta Digital vs Pix Processamento [#conta-digital-vs-pix-processamento]

| Aspecto    | Conta Digital                                             | [Pix Processamento](/docs/pix-processamento) |
| ---------- | --------------------------------------------------------- | -------------------------------------------- |
| Foco       | Conta bancária completa (Pix, TED, cartão, transferência) | Volume alto de Pix puro                      |
| Saídas     | Pix, TED, QR, dados bancários                             | Apenas Pix                                   |
| Base URL   | `https://pix.payzu.io/v1`                                 | `https://api.payzu.processamento.com/v1`     |
| Endpoints  | 13                                                        | 29                                           |
| Ideal para | Carteira, ERP, banking-as-a-service                       | Marketplace, gateway, payouts                |

## Visualizar a especificação [#visualizar-a-especificação]

<QuickLinks>
  <QuickLink href="/api-scalar-hub" title="Scalar" />

  <QuickLink href="/api-swagger-hub" title="Swagger UI" />

  <QuickLink href="/openapi/payzu-conta-digital-api.json" title="OpenAPI JSON" />
</QuickLinks>

## Outros produtos PayZu [#outros-produtos-payzu]

<QuickLinks>
  <QuickLink href="/docs/pix-processamento" title="Pix Processamento" />

  <QuickLink href="/docs" title="Todos os produtos" />
</QuickLinks>

## Precisa de ajuda? [#precisa-de-ajuda]

<QuickLinks>
  <QuickLink href="https://suporte.payzu.com.br" title="Portal de suporte" />

  <QuickLink href="https://suporte.payzu.com.br/portal/pt-br/kb/payzu" title="Base de conhecimento" />

  <QuickLink href="https://suporte.payzu.com.br/portal/pt-br/newticket?departmentId=1103699000000006907&layoutId=1103699000000074011" title="Abrir ticket" />
</QuickLinks>


# 数字账户 (/docs/conta-digital/index.zh)



**PayZu 数字账户 API** 是一个**通过 API 操作的银行账户**。您可以操作余额、接收 Pix、发送 Pix 和 TED、在 PayZu 账户之间转账、生成对账单、查询资料并使用信用卡 — 全部实时进行，24/7 不间断。适用于个人钱包、企业账户、ERP 系统以及需要 banking-as-a-service 的平台。

<QuickLinks>
  <QuickLink href="/docs/conta-digital/getting-started" title="快速入门" />

  <QuickLink href="/docs/conta-digital/authentication" title="身份认证" />

  <QuickLink href="/docs/conta-digital/depositos" title="存款" />

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

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

  <QuickLink href="/docs/conta-digital/glossary" title="术语表" />
</QuickLinks>

<Mermaid
  chart="`
flowchart LR
  Sua[&#x22;您的应用&#x22;] <--> API[&#x22;数字账户 API&#x22;]
  API --> D[&#x22;存款&#x22;]
  API --> S[&#x22;提现&#x22;]
  API --> G[&#x22;账户管理&#x22;]
  API --> CB[&#x22;Webhooks&#x22;]

  click D &#x22;/docs/conta-digital/depositos&#x22; &#x22;存款端点&#x22;
  click S &#x22;/docs/conta-digital/saques&#x22; &#x22;提现端点&#x22;
  click G &#x22;/docs/conta-digital/gestao-de-conta&#x22; &#x22;管理端点&#x22;
  click CB &#x22;/docs/conta-digital/webhooks&#x22; &#x22;Webhooks&#x22;

  style API fill:#14ce71,stroke:#0eb464,color:#ffffff
`"
/>

## 从哪里开始 [#从哪里开始]

| 如果您是               | 从这里开始                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------- |
| **首次集成**           | [快速入门](/docs/conta-digital/getting-started) → [身份认证](/docs/conta-digital/authentication) |
| **直接查看参考文档**       | [存款](/docs/conta-digital/depositos)、[提现](/docs/conta-digital/saques)                     |
| **需要理解 callbacks** | [Webhooks](/docs/conta-digital/webhooks)                                                 |
| **对账余额和对账单**       | [账户管理](/docs/conta-digital/gestao-de-conta)                                              |

## API 覆盖范围 [#api-覆盖范围]

| 分组                                          | 端点数 | 典型用途                   |
| ------------------------------------------- | --- | ---------------------- |
| [存款](/docs/conta-digital/depositos)         | 4   | 通过动态 Pix 接收付款、生成凭证、退款  |
| [提现](/docs/conta-digital/saques)            | 6   | Pix（密钥/QR/数据）、TED、内部转账 |
| [账户管理](/docs/conta-digital/gestao-de-conta) | 4   | 余额、资料、对账单、业绩汇总         |

## 特性 [#特性]

| 方面           | 值                      |
| ------------ | ---------------------- |
| 端点           | **13** 个，分为 3 个领域      |
| 身份认证         | Bearer token           |
| Content-Type | `application/json`（必填） |
| 金额           | 以雷亚尔（BRL）为单位，绝不使用分     |
| Webhooks     | 指数退避重试最多 **72 次**      |
| 可用性          | 24/7 不间断，Pix 秒级处理      |

## 环境 [#环境]

| 项            | 值                                                  |
| ------------ | -------------------------------------------------- |
| **Base URL** | `https://pix.payzu.io/v1`                          |
| **状态**       | [status.payzu.com.br](https://status.payzu.com.br) |

## 数字账户 vs Pix Processamento [#数字账户-vs-pix-processamento]

| 方面       | 数字账户                        | [Pix Processamento](/docs/pix-processamento) |
| -------- | --------------------------- | -------------------------------------------- |
| 定位       | 完整银行账户（Pix、TED、信用卡、转账）      | 大批量纯 Pix                                     |
| 出款方式     | Pix、TED、QR、银行账户数据           | 仅 Pix                                        |
| Base URL | `https://pix.payzu.io/v1`   | `https://api.payzu.processamento.com/v1`     |
| 端点数      | 13                          | 29                                           |
| 适用场景     | 钱包、ERP、banking-as-a-service | 市场平台、网关、payouts                              |

## 查看规范 [#查看规范]

<QuickLinks>
  <QuickLink href="/api-scalar-hub" title="Scalar" />

  <QuickLink href="/api-swagger-hub" title="Swagger UI" />

  <QuickLink href="/openapi/payzu-conta-digital-api.json" title="OpenAPI JSON" />
</QuickLinks>

## 其他 PayZu 产品 [#其他-payzu-产品]

<QuickLinks>
  <QuickLink href="/docs/pix-processamento" title="Pix Processamento" />

  <QuickLink href="/docs" title="所有产品" />
</QuickLinks>

## 需要帮助？ [#需要帮助]

<QuickLinks>
  <QuickLink href="https://suporte.payzu.com.br" title="支持门户" />

  <QuickLink href="https://suporte.payzu.com.br/portal/pt-br/kb/payzu" title="知识库" />

  <QuickLink href="https://suporte.payzu.com.br/portal/pt-br/newticket?departmentId=1103699000000006907&layoutId=1103699000000074011" title="提交工单" />
</QuickLinks>


# Webhooks (/docs/conta-digital/webhooks.en)



<QuickLinks>
  <QuickLink href="/docs/conta-digital/depositos" title="Deposits" />

  <QuickLink href="/docs/conta-digital/saques" title="Withdrawals" />

  <QuickLink href="/docs/conta-digital/glossary" title="Glossary" />

  <QuickLink href="/docs/conta-digital/authentication" title="Authentication" />
</QuickLinks>

The API sends a `POST` request to the `callbackUrl` provided when creating the charge or withdrawal whenever the status changes. The body is JSON with the updated transaction data.

## What is a webhook (callback) [#what-is-a-webhook-callback]

Instead of your system constantly asking "has it been paid yet?", PayZu **calls you** when something happens.

<Mermaid
  chart="`
sequenceDiagram
  participant App as Your application
  participant PZ as PayZu
  participant Banco as Customer's bank

  App->>PZ: POST /pix with callbackUrl
  PZ-->>App: id, qrCodeText, status PENDING
  Banco->>PZ: Customer pays
  PZ->>App: POST callbackUrl status COMPLETED
  App-->>PZ: HTTP 200 OK
`"
/>

## How to configure [#how-to-configure]

Pass `callbackUrl` on every creation ([`POST /pix`](/docs/conta-digital/depositos/createPixCharge), [`POST /withdraw`](/docs/conta-digital/saques/createWithdraw), etc):

```json
{
  "amount": 99.90,
  "callbackUrl": "https://seusite.com.br/webhooks/payzu",
  "clientReference": "order-2025-001"
}
```

The endpoint must be publicly accessible and respond with `HTTP 2xx` within **5 seconds**, accepting:

```http
Content-Type: application/json
```

## Retry system [#retry-system]

PayZu resends the callback **up to 72 times** with exponential backoff and jitter when it does not receive `2xx` within 5 seconds.

<Mermaid
  chart="`
flowchart TD
  A[&#x22;Transaction status change&#x22;]
  A --> B[&#x22;PayZu sends POST callbackUrl&#x22;]
  B --> C{&#x22;Response within 5s?&#x22;}
  C -->|HTTP 2xx| D[&#x22;Delivery confirmed&#x22;]
  C -->|Error or timeout| E[&#x22;Exponential backoff + jitter&#x22;]
  E --> F{&#x22;Attempt less than 72?&#x22;}
  F -->|Yes| B
  F -->|No| G[&#x22;Marked as permanent failure&#x22;]

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

## Fields sent [#fields-sent]

### Identification [#identification]

| Field               | Type   | Description                                                                       |
| ------------------- | ------ | --------------------------------------------------------------------------------- |
| `id`                | string | Unique identifier of the transaction at PayZu                                     |
| `clientReference`   | string | External identifier you provided                                                  |
| `type`              | string | `DEPOSIT` or `WITHDRAW`                                                           |
| `status`            | string | See [Transaction status](/docs/conta-digital/glossary#status-de-transação-status) |
| `amount`            | number | Amount in &#x2A;*reais (BRL)**                                                    |
| `serviceFeeCharged` | number | Fee charged                                                                       |

### Generated charge [#generated-charge]

| Field               | Type   | Description                   |
| ------------------- | ------ | ----------------------------- |
| `qrCodeText`        | string | Pix copy-and-paste code (EMV) |
| `qrCodeBase64`      | string | QR image in Base64            |
| `qrCodeUrl`         | string | Public URL of the QR as PNG   |
| `generatedName`     | string | Reference name                |
| `generatedDocument` | string | CPF or CNPJ                   |
| `generatedEmail`    | string | Linked email                  |

### Payer [#payer]

| Field                  | Type   | Description                     |
| ---------------------- | ------ | ------------------------------- |
| `payerName`            | string | Payer's name (if available)     |
| `payerDocument`        | string | Payer's document                |
| `payerInstitutionIspb` | string | ISPB of the payer's institution |
| `payerInstitutionName` | string | Name of the institution         |

### Receiver [#receiver]

| Field                     | Type   | Description                        |
| ------------------------- | ------ | ---------------------------------- |
| `receiverName`            | string | Receiver's name (if provided)      |
| `receiverDocument`        | string | Receiver's document                |
| `receiverInstitutionIspb` | string | ISPB of the receiver's institution |
| `receiverInstitutionName` | string | Name of the institution            |

### Withdrawal by key [#withdrawal-by-key]

| Field             | Type   | Description                                                              |
| ----------------- | ------ | ------------------------------------------------------------------------ |
| `withdrawPixKey`  | string | Pix key used in the withdrawal                                           |
| `withdrawPixType` | string | See [Key types](/docs/conta-digital/glossary#tipos-de-chave-pix-pixtype) |

### Timestamps and infraction [#timestamps-and-infraction]

| Field        | Type                | Description                                                                                     |
| ------------ | ------------------- | ----------------------------------------------------------------------------------------------- |
| `createdAt`  | string              | When the transaction was created (ISO 8601)                                                     |
| `updatedAt`  | string              | Last update                                                                                     |
| `paidAt`     | string \| null      | When it was paid (`null` if not yet paid)                                                       |
| `endToEndId` | string              | EndToEnd ID of the Pix                                                                          |
| `infraction` | object \| undefined | Present only in case of MED dispute, see [Glossary](/docs/conta-digital/glossary#infrações-med) |

## Best practices [#best-practices]

* **Respond fast**: return `2xx` in under 5s. Process heavy work in a queue
* **Idempotência**: store `id + status` to deduplicate
* **Use `clientReference`**: pass an external identifier on creation
* **Restrict by IP**: accept callbacks only from the official PayZu IP

## Support [#support]

<QuickLinks>
  <QuickLink href="https://suporte.payzu.com.br/portal/pt-br/newticket?departmentId=1103699000000006907&layoutId=1103699000000074011" title="Open ticket" />

  <QuickLink href="https://suporte.payzu.com.br" title="Support portal" />
</QuickLinks>


# Webhooks (/docs/conta-digital/webhooks)



<QuickLinks>
  <QuickLink href="/docs/conta-digital/depositos" title="Depósitos" />

  <QuickLink href="/docs/conta-digital/saques" title="Saques" />

  <QuickLink href="/docs/conta-digital/glossary" title="Glossário" />

  <QuickLink href="/docs/conta-digital/authentication" title="Autenticação" />
</QuickLinks>

A API envia uma requisição `POST` para a `callbackUrl` informada na criação da cobrança ou saque sempre que o status muda. O corpo é JSON com os dados atualizados da transação.

## O que é um webhook (callback) [#o-que-é-um-webhook-callback]

Em vez do seu sistema ficar perguntando "já pagou?", a PayZu **chama você** quando algo acontece.

<Mermaid
  chart="`
sequenceDiagram
  participant App as Sua aplicação
  participant PZ as PayZu
  participant Banco as Banco do cliente

  App->>PZ: POST /pix com callbackUrl
  PZ-->>App: id, qrCodeText, status PENDING
  Banco->>PZ: Cliente paga
  PZ->>App: POST callbackUrl status COMPLETED
  App-->>PZ: HTTP 200 OK
`"
/>

## Como configurar [#como-configurar]

Passe `callbackUrl` em cada criação ([`POST /pix`](/docs/conta-digital/depositos/createPixCharge), [`POST /withdraw`](/docs/conta-digital/saques/createWithdraw), etc):

```json
{
  "amount": 99.90,
  "callbackUrl": "https://seusite.com.br/webhooks/payzu",
  "clientReference": "order-2025-001"
}
```

O endpoint precisa estar acessível publicamente e responder `HTTP 2xx` em até **5 segundos**, aceitando:

```http
Content-Type: application/json
```

## Sistema de retry [#sistema-de-retry]

A PayZu reenvia o callback **até 72 vezes** com backoff exponencial e jitter quando não recebe `2xx` em 5 segundos.

<Mermaid
  chart="`
flowchart TD
  A[&#x22;Mudança de status na transação&#x22;]
  A --> B[&#x22;PayZu envia POST callbackUrl&#x22;]
  B --> C{&#x22;Resposta em 5s?&#x22;}
  C -->|HTTP 2xx| D[&#x22;Entrega confirmada&#x22;]
  C -->|Erro ou timeout| E[&#x22;Backoff exponencial + jitter&#x22;]
  E --> F{&#x22;Tentativa menor que 72?&#x22;}
  F -->|Sim| B
  F -->|Não| G[&#x22;Marca como falha definitiva&#x22;]

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

## Campos enviados [#campos-enviados]

### Identificação [#identificação]

| Campo               | Tipo   | Descrição                                                                          |
| ------------------- | ------ | ---------------------------------------------------------------------------------- |
| `id`                | string | Identificador único da transação na PayZu                                          |
| `clientReference`   | string | Identificador externo que você forneceu                                            |
| `type`              | string | `DEPOSIT` ou `WITHDRAW`                                                            |
| `status`            | string | Ver [Status de transação](/docs/conta-digital/glossary#status-de-transação-status) |
| `amount`            | number | Valor em &#x2A;*reais (BRL)**                                                      |
| `serviceFeeCharged` | number | Tarifa cobrada                                                                     |

### Cobrança gerada [#cobrança-gerada]

| Campo               | Tipo   | Descrição                     |
| ------------------- | ------ | ----------------------------- |
| `qrCodeText`        | string | Código Pix copia-e-cola (EMV) |
| `qrCodeBase64`      | string | Imagem do QR em Base64        |
| `qrCodeUrl`         | string | URL pública do QR como PNG    |
| `generatedName`     | string | Nome de referência            |
| `generatedDocument` | string | CPF ou CNPJ                   |
| `generatedEmail`    | string | Email vinculado               |

### Pagador [#pagador]

| Campo                  | Tipo   | Descrição                      |
| ---------------------- | ------ | ------------------------------ |
| `payerName`            | string | Nome do pagador (se houver)    |
| `payerDocument`        | string | Documento do pagador           |
| `payerInstitutionIspb` | string | ISPB da instituição do pagador |
| `payerInstitutionName` | string | Nome da instituição            |

### Recebedor [#recebedor]

| Campo                     | Tipo   | Descrição                        |
| ------------------------- | ------ | -------------------------------- |
| `receiverName`            | string | Nome do recebedor (se fornecido) |
| `receiverDocument`        | string | Documento do recebedor           |
| `receiverInstitutionIspb` | string | ISPB da instituição do recebedor |
| `receiverInstitutionName` | string | Nome da instituição              |

### Saque por chave [#saque-por-chave]

| Campo             | Tipo   | Descrição                                                                     |
| ----------------- | ------ | ----------------------------------------------------------------------------- |
| `withdrawPixKey`  | string | Chave Pix usada no saque                                                      |
| `withdrawPixType` | string | Ver [Tipos de chave](/docs/conta-digital/glossary#tipos-de-chave-pix-pixtype) |

### Timestamps e infração [#timestamps-e-infração]

| Campo        | Tipo                | Descrição                                                                                       |
| ------------ | ------------------- | ----------------------------------------------------------------------------------------------- |
| `createdAt`  | string              | Quando a transação foi criada (ISO 8601)                                                        |
| `updatedAt`  | string              | Última atualização                                                                              |
| `paidAt`     | string \| null      | Quando foi paga (`null` se ainda não foi)                                                       |
| `endToEndId` | string              | EndToEnd ID do Pix                                                                              |
| `infraction` | object \| undefined | Presente só em caso de disputa MED, ver [Glossário](/docs/conta-digital/glossary#infrações-med) |

## Boas práticas [#boas-práticas]

* **Responda rápido**: devolva `2xx` em menos de 5s. Processe pesado em fila
* **Idempotência**: armazene `id + status` pra deduplicar
* **Use `clientReference`**: passe identificador externo na criação
* **Restrinja por IP**: aceite callbacks apenas do IP oficial PayZu

## Suporte [#suporte]

<QuickLinks>
  <QuickLink href="https://suporte.payzu.com.br/portal/pt-br/newticket?departmentId=1103699000000006907&layoutId=1103699000000074011" title="Abrir ticket" />

  <QuickLink href="https://suporte.payzu.com.br" title="Portal de suporte" />
</QuickLinks>


# Webhooks (/docs/conta-digital/webhooks.zh)



<QuickLinks>
  <QuickLink href="/docs/conta-digital/depositos" title="存款" />

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

  <QuickLink href="/docs/conta-digital/glossary" title="术语表" />

  <QuickLink href="/docs/conta-digital/authentication" title="身份认证" />
</QuickLinks>

每当状态变化时,API 都会向创建充值或提现时提供的 `callbackUrl` 发送 `POST` 请求。请求体为 JSON,包含更新后的交易数据。

## 什么是 webhook(callback) [#什么是-webhookcallback]

无需让您的系统不断询问"已支付了吗?",当事件发生时,PayZu 会**主动调用您**。

<Mermaid
  chart="`
sequenceDiagram
  participant App as 您的应用
  participant PZ as PayZu
  participant Banco as 客户的银行

  App->>PZ: POST /pix 携带 callbackUrl
  PZ-->>App: id, qrCodeText, 状态 PENDING
  Banco->>PZ: 客户完成支付
  PZ->>App: POST callbackUrl 状态 COMPLETED
  App-->>PZ: HTTP 200 OK
`"
/>

## 如何配置 [#如何配置]

在每次创建请求中传入 `callbackUrl`([`POST /pix`](/docs/conta-digital/depositos/createPixCharge)、[`POST /withdraw`](/docs/conta-digital/saques/createWithdraw) 等):

```json
{
  "amount": 99.90,
  "callbackUrl": "https://seusite.com.br/webhooks/payzu",
  "clientReference": "order-2025-001"
}
```

该 endpoint 必须可公网访问,并在 **5 秒**内返回 `HTTP 2xx`,接受:

```http
Content-Type: application/json
```

## 重试机制 [#重试机制]

当未在 5 秒内收到 `2xx` 响应时,PayZu 会以指数退避加抖动的方式重新发送 callback,**最多 72 次**。

<Mermaid
  chart="`
flowchart TD
  A[&#x22;交易状态变化&#x22;]
  A --> B[&#x22;PayZu 发送 POST callbackUrl&#x22;]
  B --> C{&#x22;5 秒内是否响应?&#x22;}
  C -->|HTTP 2xx| D[&#x22;确认送达&#x22;]
  C -->|错误或超时| E[&#x22;指数退避 + 抖动&#x22;]
  E --> F{&#x22;尝试次数小于 72?&#x22;}
  F -->|是| B
  F -->|否| G[&#x22;标记为最终失败&#x22;]

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

## 发送的字段 [#发送的字段]

### 标识信息 [#标识信息]

| 字段                  | 类型     | 说明                                                                |
| ------------------- | ------ | ----------------------------------------------------------------- |
| `id`                | string | PayZu 中交易的唯一标识符                                                   |
| `clientReference`   | string | 您提供的外部标识符                                                         |
| `type`              | string | `DEPOSIT` 或 `WITHDRAW`                                            |
| `status`            | string | 参见[交易状态](/docs/conta-digital/glossary#status-de-transação-status) |
| `amount`            | number | 金额,单位&#x2A;*雷亚尔(BRL)**                                            |
| `serviceFeeCharged` | number | 已收取的手续费                                                           |

### 生成的收款单 [#生成的收款单]

| 字段                  | 类型     | 说明                    |
| ------------------- | ------ | --------------------- |
| `qrCodeText`        | string | Pix 复制粘贴码(EMV)        |
| `qrCodeBase64`      | string | QR Code 图像的 Base64 编码 |
| `qrCodeUrl`         | string | QR Code 的 PNG 公开 URL  |
| `generatedName`     | string | 关联名称                  |
| `generatedDocument` | string | CPF 或 CNPJ            |
| `generatedEmail`    | string | 关联邮箱                  |

### 付款方 [#付款方]

| 字段                     | 类型     | 说明            |
| ---------------------- | ------ | ------------- |
| `payerName`            | string | 付款人姓名(如果有)    |
| `payerDocument`        | string | 付款人证件号        |
| `payerInstitutionIspb` | string | 付款人所属机构的 ISPB |
| `payerInstitutionName` | string | 机构名称          |

### 收款方 [#收款方]

| 字段                        | 类型     | 说明            |
| ------------------------- | ------ | ------------- |
| `receiverName`            | string | 收款人姓名(如果提供)   |
| `receiverDocument`        | string | 收款人证件号        |
| `receiverInstitutionIspb` | string | 收款人所属机构的 ISPB |
| `receiverInstitutionName` | string | 机构名称          |

### 通过密钥提现 [#通过密钥提现]

| 字段                | 类型     | 说明                                                                |
| ----------------- | ------ | ----------------------------------------------------------------- |
| `withdrawPixKey`  | string | 提现使用的 Pix 密钥                                                      |
| `withdrawPixType` | string | 参见[密钥类型](/docs/conta-digital/glossary#tipos-de-chave-pix-pixtype) |

### 时间戳与争议 [#时间戳与争议]

| 字段           | 类型                  | 说明                                                                 |
| ------------ | ------------------- | ------------------------------------------------------------------ |
| `createdAt`  | string              | 交易创建时间(ISO 8601)                                                   |
| `updatedAt`  | string              | 最近更新时间                                                             |
| `paidAt`     | string \| null      | 支付时间(若尚未支付则为 `null`)                                               |
| `endToEndId` | string              | Pix 的 EndToEnd ID                                                  |
| `infraction` | object \| undefined | 仅在发生 MED 争议时出现,参见[术语表](/docs/conta-digital/glossary#infrações-med) |

## 最佳实践 [#最佳实践]

* **快速响应**:在 5 秒内返回 `2xx`。耗时处理放入队列异步执行
* **idempotência**:存储 `id + status` 用于去重
* **使用 `clientReference`**:在创建时传入外部标识符
* **按 IP 限制**:仅接受来自 PayZu 官方 IP 的 callback

## 支持 [#支持]

<QuickLinks>
  <QuickLink href="https://suporte.payzu.com.br/portal/pt-br/newticket?departmentId=1103699000000006907&layoutId=1103699000000074011" title="提交工单" />

  <QuickLink href="https://suporte.payzu.com.br" title="支持门户" />
</QuickLinks>


# Account Information (/docs/conta-digital/gestao-de-conta/getUser.en)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Informações da Conta (/docs/conta-digital/gestao-de-conta/getUser)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# 账户信息 (/docs/conta-digital/gestao-de-conta/getUser.zh)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Check Balances (/docs/conta-digital/gestao-de-conta/getUserBalance.en)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Consultar Saldos (/docs/conta-digital/gestao-de-conta/getUserBalance)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# 查询余额 (/docs/conta-digital/gestao-de-conta/getUserBalance.zh)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Performance Report (/docs/conta-digital/gestao-de-conta/getUserSummary.en)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Relatório de Performance (/docs/conta-digital/gestao-de-conta/getUserSummary)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# 性能报告 (/docs/conta-digital/gestao-de-conta/getUserSummary.zh)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Transaction Statement (/docs/conta-digital/gestao-de-conta/getUserTransactions.en)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Extrato de Transações (/docs/conta-digital/gestao-de-conta/getUserTransactions)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# 交易明细 (/docs/conta-digital/gestao-de-conta/getUserTransactions.zh)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Account Management (/docs/conta-digital/gestao-de-conta/index.en)



Account Management groups the **read-only** endpoints you use for reconciliation, dashboards and operational monitoring.

<QuickLinks>
  <QuickLink href="/docs/conta-digital/gestao-de-conta/getUserBalance" title="Balance" method="GET" path="/user/balance" />

  <QuickLink href="/docs/conta-digital/gestao-de-conta/getUser" title="Profile" method="GET" path="/user" />

  <QuickLink href="/docs/conta-digital/gestao-de-conta/getUserTransactions" title="Statement" method="GET" path="/user/transactions" />

  <QuickLink href="/docs/conta-digital/gestao-de-conta/getUserSummary" title="Summary" method="GET" path="/user/summary" />
</QuickLinks>

## When to use each one [#when-to-use-each-one]

| Question                                   | Endpoint                                                                            |
| ------------------------------------------ | ----------------------------------------------------------------------------------- |
| How much do I have available right now?    | [`GET /user/balance`](/docs/conta-digital/gestao-de-conta/getUserBalance)           |
| What are my account data, limits and fees? | [`GET /user`](/docs/conta-digital/gestao-de-conta/getUser)                          |
| List transactions with filters             | [`GET /user/transactions`](/docs/conta-digital/gestao-de-conta/getUserTransactions) |
| Volume, count and conversion rate          | [`GET /user/summary`](/docs/conta-digital/gestao-de-conta/getUserSummary)           |

## Examples [#examples]

<Accordions type="single">
  <Accordion title="GET /user/balance, query balance">
    ```bash
    curl https://pix.payzu.io/v1/user/balance \
      -H "Authorization: Bearer $TOKEN"
    ```

    Response:

    ```json
    {
      "available": 12450.30,
      "blocked": 320.00,
      "withdrawable": 12130.30
    }
    ```
  </Accordion>

  <Accordion title="GET /user/transactions, filter by period">
    ```bash
    curl "https://pix.payzu.io/v1/user/transactions?startDate=2026-05-01&endDate=2026-05-21&status=COMPLETED&limit=50" \
      -H "Authorization: Bearer $TOKEN"
    ```
  </Accordion>
</Accordions>

## Best practices [#best-practices]

* **Short cache** on balance (5 to 30 seconds), avoids rate limit
* **Paginate** the statement with `limit` and cursor, never fetch everything at once
* **Reconcile by `clientReference`** when comparing with your internal database
* **Use the summary** for dashboards, avoids summing transactions on the client

## Related [#related]

<QuickLinks>
  <QuickLink href="/docs/conta-digital/glossary" title="Glossary" />

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


# Gestão de Conta (/docs/conta-digital/gestao-de-conta)



Gestão de Conta concentra os endpoints **somente leitura** que você usa para conciliação, dashboard e acompanhamento operacional.

<QuickLinks>
  <QuickLink href="/docs/conta-digital/gestao-de-conta/getUserBalance" title="Saldo" method="GET" path="/user/balance" />

  <QuickLink href="/docs/conta-digital/gestao-de-conta/getUser" title="Perfil" method="GET" path="/user" />

  <QuickLink href="/docs/conta-digital/gestao-de-conta/getUserTransactions" title="Extrato" method="GET" path="/user/transactions" />

  <QuickLink href="/docs/conta-digital/gestao-de-conta/getUserSummary" title="Resumo" method="GET" path="/user/summary" />
</QuickLinks>

## Quando usar cada um [#quando-usar-cada-um]

| Pergunta                                     | Endpoint                                                                            |
| -------------------------------------------- | ----------------------------------------------------------------------------------- |
| Quanto eu tenho disponível agora?            | [`GET /user/balance`](/docs/conta-digital/gestao-de-conta/getUserBalance)           |
| Quais dados, limites e taxas da minha conta? | [`GET /user`](/docs/conta-digital/gestao-de-conta/getUser)                          |
| Listar transações com filtros                | [`GET /user/transactions`](/docs/conta-digital/gestao-de-conta/getUserTransactions) |
| Volume, contagem e taxa de conversão         | [`GET /user/summary`](/docs/conta-digital/gestao-de-conta/getUserSummary)           |

## Exemplos [#exemplos]

<Accordions type="single">
  <Accordion title="GET /user/balance, consultar saldo">
    ```bash
    curl https://pix.payzu.io/v1/user/balance \
      -H "Authorization: Bearer $TOKEN"
    ```

    Resposta:

    ```json
    {
      "available": 12450.30,
      "blocked": 320.00,
      "withdrawable": 12130.30
    }
    ```
  </Accordion>

  <Accordion title="GET /user/transactions, filtrar por período">
    ```bash
    curl "https://pix.payzu.io/v1/user/transactions?startDate=2026-05-01&endDate=2026-05-21&status=COMPLETED&limit=50" \
      -H "Authorization: Bearer $TOKEN"
    ```
  </Accordion>
</Accordions>

## Boas práticas [#boas-práticas]

* **Cache curto** no saldo (5 a 30 segundos), evita rate limit
* **Pagine** o extrato com `limit` e cursor, nunca pegue tudo de uma vez
* **Reconcilie por `clientReference`** quando comparar com seu banco de dados interno
* **Use o resumo** para dashboards, evita somar transações no cliente

## Relacionados [#relacionados]

<QuickLinks>
  <QuickLink href="/docs/conta-digital/glossary" title="Glossário" />

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


# 账户管理 (/docs/conta-digital/gestao-de-conta/index.zh)



账户管理汇集了用于对账、仪表板和运营跟踪的**只读**端点。

<QuickLinks>
  <QuickLink href="/docs/conta-digital/gestao-de-conta/getUserBalance" title="余额" method="GET" path="/user/balance" />

  <QuickLink href="/docs/conta-digital/gestao-de-conta/getUser" title="账户资料" method="GET" path="/user" />

  <QuickLink href="/docs/conta-digital/gestao-de-conta/getUserTransactions" title="交易记录" method="GET" path="/user/transactions" />

  <QuickLink href="/docs/conta-digital/gestao-de-conta/getUserSummary" title="汇总" method="GET" path="/user/summary" />
</QuickLinks>

## 何时使用哪个端点 [#何时使用哪个端点]

| 问题               | 端点                                                                                  |
| ---------------- | ----------------------------------------------------------------------------------- |
| 我现在有多少可用余额？      | [`GET /user/balance`](/docs/conta-digital/gestao-de-conta/getUserBalance)           |
| 我账户的数据、额度和费率是什么？ | [`GET /user`](/docs/conta-digital/gestao-de-conta/getUser)                          |
| 按筛选条件列出交易        | [`GET /user/transactions`](/docs/conta-digital/gestao-de-conta/getUserTransactions) |
| 交易量、计数和转化率       | [`GET /user/summary`](/docs/conta-digital/gestao-de-conta/getUserSummary)           |

## 示例 [#示例]

<Accordions type="single">
  <Accordion title="GET /user/balance，查询余额">
    ```bash
    curl https://pix.payzu.io/v1/user/balance \
      -H "Authorization: Bearer $TOKEN"
    ```

    响应：

    ```json
    {
      "available": 12450.30,
      "blocked": 320.00,
      "withdrawable": 12130.30
    }
    ```
  </Accordion>

  <Accordion title="GET /user/transactions，按时间段筛选">
    ```bash
    curl "https://pix.payzu.io/v1/user/transactions?startDate=2026-05-01&endDate=2026-05-21&status=COMPLETED&limit=50" \
      -H "Authorization: Bearer $TOKEN"
    ```
  </Accordion>
</Accordions>

## 最佳实践 [#最佳实践]

* 余额使用**短期缓存**（5 到 30 秒），避免触发限流
* 使用 `limit` 和 cursor **分页**获取交易记录，切勿一次性全部拉取
* 与内部数据库对比时，**按 `clientReference` 对账**
* 仪表板**使用汇总接口**，避免在客户端累加交易

## 相关内容 [#相关内容]

<QuickLinks>
  <QuickLink href="/docs/conta-digital/glossary" title="术语表" />

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


# Create PIX Charge (/docs/conta-digital/depositos/createPixCharge.en)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Criar Cobrança PIX (/docs/conta-digital/depositos/createPixCharge)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# 创建 PIX 收款 (/docs/conta-digital/depositos/createPixCharge.zh)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Query Transaction (/docs/conta-digital/depositos/getPixTransaction.en)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Consultar Transação (/docs/conta-digital/depositos/getPixTransaction)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# 查询交易 (/docs/conta-digital/depositos/getPixTransaction.zh)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Download Receipt (/docs/conta-digital/depositos/getTransactionProof.en)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Baixar Comprovante (/docs/conta-digital/depositos/getTransactionProof)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# 下载凭证 (/docs/conta-digital/depositos/getTransactionProof.zh)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Deposits (/docs/conta-digital/depositos/index.en)



Deposits are the **money-in** path to your account. You generate the QR Code, show it to the customer, and PayZu notifies you when they pay. All transactions in this group are of type `DEPOSIT`.

<QuickLinks>
  <QuickLink href="/docs/conta-digital/depositos/createPixCharge" title="Create charge" method="POST" path="/pix" />

  <QuickLink href="/docs/conta-digital/depositos/getPixTransaction" title="Get transaction" method="GET" path="/pix/{id}" />

  <QuickLink href="/docs/conta-digital/depositos/getTransactionProof" title="Receipt" method="GET" path="/proof/{id}" />

  <QuickLink href="/docs/conta-digital/depositos/refundPixTransaction" title="Refund" method="POST" path="/pix/refund/{id}" />
</QuickLinks>

## When to use each [#when-to-use-each]

| Question                                 | Endpoint                                                                      |
| ---------------------------------------- | ----------------------------------------------------------------------------- |
| I want to charge a customer              | [`POST /pix`](/docs/conta-digital/depositos/createPixCharge)                  |
| Did the customer pay? What's the status? | [`GET /pix/{id}`](/docs/conta-digital/depositos/getPixTransaction)            |
| Customer requested the official receipt  | [`GET /proof/{id}`](/docs/conta-digital/depositos/getTransactionProof)        |
| I need to return a received amount       | [`POST /pix/refund/{id}`](/docs/conta-digital/depositos/refundPixTransaction) |

<Callout type="info">
  The Digital Account supports only **dynamic** QR Code (with amount and ID per charge). Static QR is not processed.
</Callout>

## Examples [#examples]

<Accordions type="single">
  <Accordion title="POST /pix, create a simple charge">
    ```bash
    curl -X POST https://pix.payzu.io/v1/pix \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 99.90,
        "clientReference": "order-1234",
        "callbackUrl": "https://yoursite.com/webhooks/payzu"
      }'
    ```

    Response:

    ```json
    {
      "id": "PZ_xxx",
      "status": "PENDING",
      "amount": 99.90,
      "clientReference": "order-1234",
      "qrCodeText": "00020126870014br.gov.bcb.pix...",
      "qrCodeUrl": "https://pix.payzu.io/v1/pix/qr-code/PZ_xxx"
    }
    ```
  </Accordion>

  <Accordion title="POST /pix/refund/{id}, refund a received amount">
    ```bash
    curl -X POST https://pix.payzu.io/v1/pix/refund/PZ_xxx \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "amount": 50.00 }'
    ```
  </Accordion>
</Accordions>

## Recommended flow [#recommended-flow]

<Mermaid
  chart="`
flowchart LR
  A[&#x22;POST /pix&#x22;] --> B[&#x22;Display QR&#x22;]
  B --> C[&#x22;Customer pays&#x22;]
  C --> D[&#x22;Callback COMPLETED&#x22;]
  D --> E[&#x22;Mark order paid&#x22;]
  E --> F[&#x22;GET /proof optional&#x22;]

  click A &#x22;/docs/conta-digital/depositos/createPixCharge&#x22; &#x22;POST /pix&#x22;
  click D &#x22;/docs/conta-digital/webhooks&#x22; &#x22;Webhooks&#x22;
  click F &#x22;/docs/conta-digital/depositos/getTransactionProof&#x22; &#x22;GET /proof&#x22;

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

## Related [#related]

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

  <QuickLink href="/docs/conta-digital/glossary" title="Glossary" />

  <QuickLink href="/docs/conta-digital/saques" title="Withdrawals" />
</QuickLinks>


# Depósitos (/docs/conta-digital/depositos)



Depósitos são o caminho de **entrada de dinheiro** na sua conta. Você gera o QR Code, mostra ao cliente, e a PayZu te avisa quando ele paga. Todas as transações deste grupo são do tipo `DEPOSIT`.

<QuickLinks>
  <QuickLink href="/docs/conta-digital/depositos/createPixCharge" title="Criar cobrança" method="POST" path="/pix" />

  <QuickLink href="/docs/conta-digital/depositos/getPixTransaction" title="Consultar transação" method="GET" path="/pix/{id}" />

  <QuickLink href="/docs/conta-digital/depositos/getTransactionProof" title="Comprovante" method="GET" path="/proof/{id}" />

  <QuickLink href="/docs/conta-digital/depositos/refundPixTransaction" title="Estornar" method="POST" path="/pix/refund/{id}" />
</QuickLinks>

## Quando usar cada um [#quando-usar-cada-um]

| Pergunta                            | Endpoint                                                                      |
| ----------------------------------- | ----------------------------------------------------------------------------- |
| Quero cobrar um cliente             | [`POST /pix`](/docs/conta-digital/depositos/createPixCharge)                  |
| Cliente pagou? Qual o status agora? | [`GET /pix/{id}`](/docs/conta-digital/depositos/getPixTransaction)            |
| Cliente pediu o comprovante oficial | [`GET /proof/{id}`](/docs/conta-digital/depositos/getTransactionProof)        |
| Preciso devolver valor recebido     | [`POST /pix/refund/{id}`](/docs/conta-digital/depositos/refundPixTransaction) |

<Callout type="info">
  A Conta Digital suporta apenas QR Code **dinâmico** (com valor e ID por cobrança). QR estático não é processado.
</Callout>

## Exemplos [#exemplos]

<Accordions type="single">
  <Accordion title="POST /pix, criar cobrança simples">
    ```bash
    curl -X POST https://pix.payzu.io/v1/pix \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 99.90,
        "clientReference": "order-1234",
        "callbackUrl": "https://seusite.com.br/webhooks/payzu"
      }'
    ```

    Resposta:

    ```json
    {
      "id": "PZ_xxx",
      "status": "PENDING",
      "amount": 99.90,
      "clientReference": "order-1234",
      "qrCodeText": "00020126870014br.gov.bcb.pix...",
      "qrCodeUrl": "https://pix.payzu.io/v1/pix/qr-code/PZ_xxx"
    }
    ```
  </Accordion>

  <Accordion title="POST /pix/refund/{id}, estornar valor recebido">
    ```bash
    curl -X POST https://pix.payzu.io/v1/pix/refund/PZ_xxx \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "amount": 50.00 }'
    ```
  </Accordion>
</Accordions>

## Fluxo recomendado [#fluxo-recomendado]

<Mermaid
  chart="`
flowchart LR
  A[&#x22;POST /pix&#x22;] --> B[&#x22;Exibe QR&#x22;]
  B --> C[&#x22;Cliente paga&#x22;]
  C --> D[&#x22;Callback COMPLETED&#x22;]
  D --> E[&#x22;Marca pedido pago&#x22;]
  E --> F[&#x22;GET /proof opcional&#x22;]

  click A &#x22;/docs/conta-digital/depositos/createPixCharge&#x22; &#x22;POST /pix&#x22;
  click D &#x22;/docs/conta-digital/webhooks&#x22; &#x22;Webhooks&#x22;
  click F &#x22;/docs/conta-digital/depositos/getTransactionProof&#x22; &#x22;GET /proof&#x22;

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

## Relacionados [#relacionados]

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

  <QuickLink href="/docs/conta-digital/glossary" title="Glossário" />

  <QuickLink href="/docs/conta-digital/saques" title="Saques" />
</QuickLinks>


# 收款 (/docs/conta-digital/depositos/index.zh)



收款是资金**流入**您账户的途径。您生成 QR Code，展示给客户，PayZu 会在客户付款时通知您。本组中所有交易类型均为 `DEPOSIT`。

<QuickLinks>
  <QuickLink href="/docs/conta-digital/depositos/createPixCharge" title="创建收款" method="POST" path="/pix" />

  <QuickLink href="/docs/conta-digital/depositos/getPixTransaction" title="查询交易" method="GET" path="/pix/{id}" />

  <QuickLink href="/docs/conta-digital/depositos/getTransactionProof" title="凭证" method="GET" path="/proof/{id}" />

  <QuickLink href="/docs/conta-digital/depositos/refundPixTransaction" title="退款" method="POST" path="/pix/refund/{id}" />
</QuickLinks>

## 何时使用各 endpoint [#何时使用各-endpoint]

| 问题              | Endpoint                                                                      |
| --------------- | ----------------------------------------------------------------------------- |
| 我想向客户收款         | [`POST /pix`](/docs/conta-digital/depositos/createPixCharge)                  |
| 客户付款了吗？当前状态是什么？ | [`GET /pix/{id}`](/docs/conta-digital/depositos/getPixTransaction)            |
| 客户索要正式凭证        | [`GET /proof/{id}`](/docs/conta-digital/depositos/getTransactionProof)        |
| 我需要退还已收的金额      | [`POST /pix/refund/{id}`](/docs/conta-digital/depositos/refundPixTransaction) |

<Callout type="info">
  Conta Digital 仅支持**动态** QR Code（每笔收款带有金额和 ID）。静态 QR 不予处理。
</Callout>

## 示例 [#示例]

<Accordions type="single">
  <Accordion title="POST /pix，创建简单收款">
    ```bash
    curl -X POST https://pix.payzu.io/v1/pix \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 99.90,
        "clientReference": "order-1234",
        "callbackUrl": "https://seusite.com.br/webhooks/payzu"
      }'
    ```

    响应：

    ```json
    {
      "id": "PZ_xxx",
      "status": "PENDING",
      "amount": 99.90,
      "clientReference": "order-1234",
      "qrCodeText": "00020126870014br.gov.bcb.pix...",
      "qrCodeUrl": "https://pix.payzu.io/v1/pix/qr-code/PZ_xxx"
    }
    ```
  </Accordion>

  <Accordion title="POST /pix/refund/{id}，退款已收金额">
    ```bash
    curl -X POST https://pix.payzu.io/v1/pix/refund/PZ_xxx \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "amount": 50.00 }'
    ```
  </Accordion>
</Accordions>

## 推荐流程 [#推荐流程]

<Mermaid
  chart="`
flowchart LR
  A[&#x22;POST /pix&#x22;] --> B[&#x22;展示 QR&#x22;]
  B --> C[&#x22;客户付款&#x22;]
  C --> D[&#x22;回调 COMPLETED&#x22;]
  D --> E[&#x22;标记订单已支付&#x22;]
  E --> F[&#x22;GET /proof 可选&#x22;]

  click A &#x22;/docs/conta-digital/depositos/createPixCharge&#x22; &#x22;POST /pix&#x22;
  click D &#x22;/docs/conta-digital/webhooks&#x22; &#x22;Webhooks&#x22;
  click F &#x22;/docs/conta-digital/depositos/getTransactionProof&#x22; &#x22;GET /proof&#x22;

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

## 相关内容 [#相关内容]

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

  <QuickLink href="/docs/conta-digital/glossary" title="术语表" />

  <QuickLink href="/docs/conta-digital/saques" title="提现" />
</QuickLinks>


# Refund Transaction (/docs/conta-digital/depositos/refundPixTransaction.en)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Estornar Transação (/docs/conta-digital/depositos/refundPixTransaction)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# 退款交易 (/docs/conta-digital/depositos/refundPixTransaction.zh)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Internal Transfer (/docs/conta-digital/saques/createInternalTransfer.en)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Transferência Interna (/docs/conta-digital/saques/createInternalTransfer)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# 内部转账 (/docs/conta-digital/saques/createInternalTransfer.zh)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Transfer via PIX Key (/docs/conta-digital/saques/createWithdraw.en)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Transferir via Chave PIX (/docs/conta-digital/saques/createWithdraw)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# 通过 PIX 密钥转账 (/docs/conta-digital/saques/createWithdraw.zh)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Transfer via Bank Data (/docs/conta-digital/saques/createWithdrawBankData.en)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Transferir via Dados Bancários (/docs/conta-digital/saques/createWithdrawBankData)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# 通过银行数据转账 (/docs/conta-digital/saques/createWithdrawBankData.zh)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Transfer via QR Code (/docs/conta-digital/saques/createWithdrawQrCode.en)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Transferir via QR Code (/docs/conta-digital/saques/createWithdrawQrCode)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# 通过二维码转账 (/docs/conta-digital/saques/createWithdrawQrCode.zh)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# TED Transfer (/docs/conta-digital/saques/createWithdrawTed.en)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Transferir via TED (/docs/conta-digital/saques/createWithdrawTed)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# 通过 TED 转账 (/docs/conta-digital/saques/createWithdrawTed.zh)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Download Receipt (/docs/conta-digital/saques/getTransactionProof.en)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Baixar Comprovante (/docs/conta-digital/saques/getTransactionProof)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# 下载凭证 (/docs/conta-digital/saques/getTransactionProof.zh)



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}




# Withdrawals (/docs/conta-digital/saques/index.en)



Withdrawals are the **money out** path from your account. You choose the most suitable method (Pix, TED or internal transfer) and PayZu processes the balance debit. All transactions in this group are of type `WITHDRAW`.

<QuickLinks>
  <QuickLink href="/docs/conta-digital/saques/createWithdraw" title="Withdraw by Pix key" method="POST" path="/withdraw" />

  <QuickLink href="/docs/conta-digital/saques/createWithdrawBankData" title="Withdraw by bank data" method="POST" path="/withdraw/bank-data" />

  <QuickLink href="/docs/conta-digital/saques/createWithdrawTed" title="TED" method="POST" path="/ted" />

  <QuickLink href="/docs/conta-digital/saques/createWithdrawQrCode" title="Pay QR Code" method="POST" path="/withdraw/qrcode" />

  <QuickLink href="/docs/conta-digital/saques/createInternalTransfer" title="Internal transfer" method="POST" path="/internal-transfer" />

  <QuickLink href="/docs/conta-digital/saques/getTransactionProof" title="Receipt" method="GET" path="/proof/{id}" />
</QuickLinks>

## Which method to choose [#which-method-to-choose]

| Scenario                            | Endpoint                                                                        |
| ----------------------------------- | ------------------------------------------------------------------------------- |
| I have a Pix key (CPF, email, EVP)  | [`POST /withdraw`](/docs/conta-digital/saques/createWithdraw)                   |
| I have bank/branch/account (no key) | [`POST /withdraw/bank-data`](/docs/conta-digital/saques/createWithdrawBankData) |
| I need to send a TED                | [`POST /ted`](/docs/conta-digital/saques/createWithdrawTed)                     |
| I have a QR Code to pay             | [`POST /withdraw/qrcode`](/docs/conta-digital/saques/createWithdrawQrCode)      |
| Recipient also has a PayZu account  | [`POST /internal-transfer`](/docs/conta-digital/saques/createInternalTransfer)  |
| Customer requested the receipt      | [`GET /proof/{id}`](/docs/conta-digital/saques/getTransactionProof)             |

<Callout type="warn">
  Balance is debited **before** sending. If the operation fails (invalid key, bank unavailable), the amount is automatically refunded and the status becomes `CANCELED`.
</Callout>

## Examples [#examples]

<Accordions type="single">
  <Accordion title="POST /withdraw, withdrawal by Pix key">
    ```bash
    curl -X POST https://pix.payzu.io/v1/withdraw \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 250.00,
        "pixKey": "12345678901",
        "pixType": "cpf",
        "clientReference": "payout-001",
        "callbackUrl": "https://seusite.com.br/webhooks/payzu"
      }'
    ```
  </Accordion>

  <Accordion title="POST /internal-transfer, transfer to another PayZu account">
    ```bash
    curl -X POST https://pix.payzu.io/v1/internal-transfer \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 100.00,
        "targetEmail": "destinatario@dominio.com.br",
        "clientReference": "transfer-001"
      }'
    ```
  </Accordion>
</Accordions>

## Recommended flow [#recommended-flow]

<Mermaid
  chart="`
flowchart LR
  A[&#x22;Validate balance&#x22;] --> B[&#x22;POST /withdraw&#x22;]
  B --> C{&#x22;Status&#x22;}
  C -->|PENDING| D[&#x22;Awaiting processing&#x22;]
  D --> E[&#x22;Callback COMPLETED&#x22;]
  C -->|CANCELED| F[&#x22;Balance refunded&#x22;]

  click B &#x22;/docs/conta-digital/saques/createWithdraw&#x22; &#x22;POST /withdraw&#x22;
  click E &#x22;/docs/conta-digital/webhooks&#x22; &#x22;Webhooks&#x22;

  style B fill:#f59e0b,stroke:#d97706,color:#ffffff
  style E fill:#14ce71,stroke:#0eb464,color:#ffffff
  style F fill:#ef4444,stroke:#dc2626,color:#ffffff
`"
/>

## Related [#related]

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

  <QuickLink href="/docs/conta-digital/glossary" title="Glossary" />

  <QuickLink href="/docs/conta-digital/gestao-de-conta/getUserBalance" title="Check balance" />
</QuickLinks>


# Saques (/docs/conta-digital/saques)



Saques são o caminho de **saída de dinheiro** da sua conta. Você escolhe a via mais adequada (Pix, TED ou transferência interna) e a PayZu processa o débito do saldo. Todas as transações deste grupo são do tipo `WITHDRAW`.

<QuickLinks>
  <QuickLink href="/docs/conta-digital/saques/createWithdraw" title="Saque por chave Pix" method="POST" path="/withdraw" />

  <QuickLink href="/docs/conta-digital/saques/createWithdrawBankData" title="Saque por dados bancários" method="POST" path="/withdraw/bank-data" />

  <QuickLink href="/docs/conta-digital/saques/createWithdrawTed" title="TED" method="POST" path="/ted" />

  <QuickLink href="/docs/conta-digital/saques/createWithdrawQrCode" title="Pagar QR Code" method="POST" path="/withdraw/qrcode" />

  <QuickLink href="/docs/conta-digital/saques/createInternalTransfer" title="Transferência interna" method="POST" path="/internal-transfer" />

  <QuickLink href="/docs/conta-digital/saques/getTransactionProof" title="Comprovante" method="GET" path="/proof/{id}" />
</QuickLinks>

## Qual via escolher [#qual-via-escolher]

| Cenário                                | Endpoint                                                                        |
| -------------------------------------- | ------------------------------------------------------------------------------- |
| Tenho uma chave Pix (CPF, e-mail, EVP) | [`POST /withdraw`](/docs/conta-digital/saques/createWithdraw)                   |
| Tenho banco/agência/conta (sem chave)  | [`POST /withdraw/bank-data`](/docs/conta-digital/saques/createWithdrawBankData) |
| Preciso enviar TED                     | [`POST /ted`](/docs/conta-digital/saques/createWithdrawTed)                     |
| Tenho um QR Code para pagar            | [`POST /withdraw/qrcode`](/docs/conta-digital/saques/createWithdrawQrCode)      |
| Destinatário também tem conta PayZu    | [`POST /internal-transfer`](/docs/conta-digital/saques/createInternalTransfer)  |
| Cliente pediu o comprovante            | [`GET /proof/{id}`](/docs/conta-digital/saques/getTransactionProof)             |

<Callout type="warn">
  Saldo é debitado **antes** do envio. Se a operação falhar (chave inválida, banco indisponível), o valor é estornado automaticamente e o status vira `CANCELED`.
</Callout>

## Exemplos [#exemplos]

<Accordions type="single">
  <Accordion title="POST /withdraw, saque por chave Pix">
    ```bash
    curl -X POST https://pix.payzu.io/v1/withdraw \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 250.00,
        "pixKey": "12345678901",
        "pixType": "cpf",
        "clientReference": "payout-001",
        "callbackUrl": "https://seusite.com.br/webhooks/payzu"
      }'
    ```
  </Accordion>

  <Accordion title="POST /internal-transfer, transferir para outra conta PayZu">
    ```bash
    curl -X POST https://pix.payzu.io/v1/internal-transfer \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 100.00,
        "targetEmail": "destinatario@dominio.com.br",
        "clientReference": "transfer-001"
      }'
    ```
  </Accordion>
</Accordions>

## Fluxo recomendado [#fluxo-recomendado]

<Mermaid
  chart="`
flowchart LR
  A[&#x22;Valida saldo&#x22;] --> B[&#x22;POST /withdraw&#x22;]
  B --> C{&#x22;Status&#x22;}
  C -->|PENDING| D[&#x22;Aguarda processamento&#x22;]
  D --> E[&#x22;Callback COMPLETED&#x22;]
  C -->|CANCELED| F[&#x22;Saldo estornado&#x22;]

  click B &#x22;/docs/conta-digital/saques/createWithdraw&#x22; &#x22;POST /withdraw&#x22;
  click E &#x22;/docs/conta-digital/webhooks&#x22; &#x22;Webhooks&#x22;

  style B fill:#f59e0b,stroke:#d97706,color:#ffffff
  style E fill:#14ce71,stroke:#0eb464,color:#ffffff
  style F fill:#ef4444,stroke:#dc2626,color:#ffffff
`"
/>

## Relacionados [#relacionados]

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

  <QuickLink href="/docs/conta-digital/glossary" title="Glossário" />

  <QuickLink href="/docs/conta-digital/gestao-de-conta/getUserBalance" title="Consultar saldo" />
</QuickLinks>


# 提现 (/docs/conta-digital/saques/index.zh)



提现是您账户的**资金出口**。您选择最合适的方式（Pix、TED 或内部转账），PayZu 处理余额扣款。本组中的所有交易类型均为 `WITHDRAW`。

<QuickLinks>
  <QuickLink href="/docs/conta-digital/saques/createWithdraw" title="通过 Pix 密钥提现" method="POST" path="/withdraw" />

  <QuickLink href="/docs/conta-digital/saques/createWithdrawBankData" title="通过银行数据提现" method="POST" path="/withdraw/bank-data" />

  <QuickLink href="/docs/conta-digital/saques/createWithdrawTed" title="TED" method="POST" path="/ted" />

  <QuickLink href="/docs/conta-digital/saques/createWithdrawQrCode" title="支付 QR Code" method="POST" path="/withdraw/qrcode" />

  <QuickLink href="/docs/conta-digital/saques/createInternalTransfer" title="内部转账" method="POST" path="/internal-transfer" />

  <QuickLink href="/docs/conta-digital/saques/getTransactionProof" title="凭证" method="GET" path="/proof/{id}" />
</QuickLinks>

## 选择哪种方式 [#选择哪种方式]

| 场景                      | Endpoint                                                                        |
| ----------------------- | ------------------------------------------------------------------------------- |
| 我有 Pix 密钥（CPF、电子邮件、EVP） | [`POST /withdraw`](/docs/conta-digital/saques/createWithdraw)                   |
| 我有银行/分行/账号（无密钥）         | [`POST /withdraw/bank-data`](/docs/conta-digital/saques/createWithdrawBankData) |
| 我需要发送 TED               | [`POST /ted`](/docs/conta-digital/saques/createWithdrawTed)                     |
| 我有要支付的 QR Code          | [`POST /withdraw/qrcode`](/docs/conta-digital/saques/createWithdrawQrCode)      |
| 收款人也有 PayZu 账户          | [`POST /internal-transfer`](/docs/conta-digital/saques/createInternalTransfer)  |
| 客户要求凭证                  | [`GET /proof/{id}`](/docs/conta-digital/saques/getTransactionProof)             |

<Callout type="warn">
  余额在发送**之前**被扣除。如果操作失败（密钥无效、银行不可用），金额会自动退回，状态变为 `CANCELED`。
</Callout>

## 示例 [#示例]

<Accordions type="single">
  <Accordion title="POST /withdraw，通过 Pix 密钥提现">
    ```bash
    curl -X POST https://pix.payzu.io/v1/withdraw \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 250.00,
        "pixKey": "12345678901",
        "pixType": "cpf",
        "clientReference": "payout-001",
        "callbackUrl": "https://seusite.com.br/webhooks/payzu"
      }'
    ```
  </Accordion>

  <Accordion title="POST /internal-transfer，转账到另一个 PayZu 账户">
    ```bash
    curl -X POST https://pix.payzu.io/v1/internal-transfer \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 100.00,
        "targetEmail": "destinatario@dominio.com.br",
        "clientReference": "transfer-001"
      }'
    ```
  </Accordion>
</Accordions>

## 推荐流程 [#推荐流程]

<Mermaid
  chart="`
flowchart LR
  A[&#x22;验证余额&#x22;] --> B[&#x22;POST /withdraw&#x22;]
  B --> C{&#x22;状态&#x22;}
  C -->|PENDING| D[&#x22;等待处理&#x22;]
  D --> E[&#x22;回调 COMPLETED&#x22;]
  C -->|CANCELED| F[&#x22;余额已退回&#x22;]

  click B &#x22;/docs/conta-digital/saques/createWithdraw&#x22; &#x22;POST /withdraw&#x22;
  click E &#x22;/docs/conta-digital/webhooks&#x22; &#x22;Webhooks&#x22;

  style B fill:#f59e0b,stroke:#d97706,color:#ffffff
  style E fill:#14ce71,stroke:#0eb464,color:#ffffff
  style F fill:#ef4444,stroke:#dc2626,color:#ffffff
`"
/>

## 相关内容 [#相关内容]

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

  <QuickLink href="/docs/conta-digital/glossary" title="术语表" />

  <QuickLink href="/docs/conta-digital/gestao-de-conta/getUserBalance" title="查询余额" />
</QuickLinks>