# Conta Digital (/docs/conta-digital)

Cada credencial opera uma conta só: nenhuma rota recebe `accountId`. Para operar duas contas, use duas credenciais.

<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/endpoints" title="Referência da API" />

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

  <QuickLink href="/docs/conta-digital/error-codes" title="Códigos de erro" />

  <QuickLink href="/docs/conta-digital/for-ai" title="Para IAs" />
</QuickLinks>

<Mermaid
  chart="`
flowchart LR
  Loja[&#x22;Sua aplicação&#x22;] -->|&#x22;credencial&#x22;| API[&#x22;API Conta Digital&#x22;]
  API --> CB[&#x22;Cobranças Pix&#x22;]
  API --> SQ[&#x22;Saques e pagamento de Pix copia e cola&#x22;]
  API --> TR[&#x22;Transferências entre contas&#x22;]
  API --> EX[&#x22;Saldo e extrato&#x22;]
  API -.->|&#x22;webhooks&#x22;| Loja

  click CB &#x22;/docs/conta-digital/charges&#x22; &#x22;Cobranças&#x22;
  click SQ &#x22;/docs/conta-digital/withdrawals&#x22; &#x22;Saques&#x22;
  click TR &#x22;/docs/conta-digital/internal-transfers&#x22; &#x22;Transferências&#x22;
  click EX &#x22;/docs/conta-digital/statement&#x22; &#x22;Extrato&#x22;

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

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

| Se você quer                 | Comece por                                                                                                   |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Fazer a primeira chamada** | [Primeiros passos](/docs/conta-digital/getting-started) → [Autenticação](/docs/conta-digital/authentication) |
| **Receber por Pix**          | [Cobranças Pix](/docs/conta-digital/charges)                                                                 |
| **Pagar alguém**             | [Saques Pix](/docs/conta-digital/withdrawals) ou [Pagar Pix copia e cola](/docs/conta-digital/qr-payments)   |
| **Mover saldo entre lojas**  | [Transferências entre contas](/docs/conta-digital/internal-transfers)                                        |
| **Conciliar**                | [Saldo, extrato e limites](/docs/conta-digital/statement)                                                    |
| **Acompanhar cada mudança**  | [Webhooks](/docs/conta-digital/webhooks)                                                                     |
| **Ir direto às rotas**       | [Referência da API](/docs/conta-digital/endpoints)                                                           |

## Convenções [#convenções]

| Item        | Regra                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Base URL    | `https://api.hub.payzu.com.br/api/v1`                                                                                        |
| Valores     | Inteiros, em centavos: `1500` é R$ 15,00.                                                                                    |
| Percentuais | Em basis points: `150` é 1,5%.                                                                                               |
| Datas       | ISO 8601 em UTC, como `2026-10-05T14:32:05.123Z`.                                                                            |
| Listagens   | Paginam por cursor: mande o `nextCursor` da resposta no parâmetro `cursor` da próxima chamada. Na última página ele não vem. |
| Erros       | `{ "message", "code", "details" }`. Trate pelo `code`; a `message` é um texto para exibir.                                   |

## Quando o saldo muda [#quando-o-saldo-muda]

| Operação                              | O saldo muda                                                                                  |
| ------------------------------------- | --------------------------------------------------------------------------------------------- |
| Cobrança                              | Quando o cliente paga. Chega o webhook `PAYMENT_PAID`.                                        |
| Saque e pagamento de Pix copia e cola | Na hora do pedido: o valor e a tarifa saem do saldo disponível. Se a operação falhar, voltam. |
| Transferência entre contas            | Na hora: a resposta já traz o resultado.                                                      |
| Pix recebido sem cobrança             | Quando o Pix cai. Chega o webhook `DEPOSIT_RECEIVED`.                                         |
| Estorno e devolução de depósito       | Na hora do pedido: o valor e a tarifa saem do saldo disponível. Se o estorno falhar, voltam.  |

## O que não passa pela API [#o-que-não-passa-pela-api]

* **Boleto e cartão.** A API não emite boleto nem cobra cartão. Para cartão, veja a [API de Cartões](/docs/cartao).
* **Responder contestação MED.** A API mostra a contestação; a resposta é dada no painel.
* **Criar ou trocar credencial.** Feito pelo titular, no painel [hub.payzu.com.br](https://hub.payzu.com.br).

## Ajuda [#ajuda]

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

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