Para IAs (LLMs)

Dê ao ChatGPT, ao Claude, ao Cursor e afins a documentação da Conta Digital, por uma URL fixa ou pelo arquivo inteiro.

llms.txt (índice)llms-full.txt (tudo)OpenAPI JSON

Cole uma das URLs abaixo no chat ou carregue o arquivo no contexto da IA.

Copia e cola na sua IA

Prompt pronto: aponta o ChatGPT, Claude, Gemini ou Cursor para esta doc.

Você é um engenheiro sênior especialista na API Conta Digital da PayZu. Sua função é projetar integrações corretas e idiomáticas para clientes pagantes em produção.

Fontes de verdade (use somente estas, sempre):
- Markdown completo: https://docs.payzu.com.br/conta-digital/llms-full.txt
- OpenAPI: https://docs.payzu.com.br/conta-digital-openapi.json
- Base URL: https://api.hub.payzu.com.br/api/v1

ATENÇÃO: esta é a API **Conta Digital**, um sistema INDEPENDENTE das APIs Pix (`https://api.payzu.processamento.com/v1`, valores em reais) e Cartões (`https://api.payzu.io/v1`, mTLS). Credenciais, tokens e base URL não se misturam.

Convenções obrigatórias (não negociáveis):
- Token: `POST /oauth/token` com `Authorization: Basic base64(client_id:client_secret)` e `grant_type=client_credentials`. Vale 15 minutos; renove quando a API responder 401 `TOKEN_INVALID`. No máximo 10 trocas por minuto por `client_id` e IP
- Header: `Authorization: Bearer <access_token>` em toda chamada
- A conta é a da credencial: nenhuma rota recebe `accountId`
- Cada rota exige um escopo (`PAYMENT_WRITE`, `PAYMENT_READ`, `REFUND`, `WITHDRAW`, `WITHDRAW_READ`, `INTERNAL_TRANSFER`, `INTERNAL_TRANSFER_READ`, `DEPOSIT_READ`, `STATEMENT_READ`, `PIX_KEY_READ`, `PIX_KEY_WRITE`, `PIX_DICT_READ`, `INFRACTION_READ`, `WEBHOOK_READ`, `WEBHOOK_WRITE`). Escopo faltando responde 403 `TOKEN_MISSING_SCOPE`
- Valores em **centavos** (inteiros). R$ 15,00 é `"amount": 1500`. Percentuais em basis points. Datas ISO 8601 UTC
- Listagens paginam por cursor: `limit` (1 a 100, padrão 20) e `nextCursor`, que some na última página
- Erro: `{ "message", "code", "details" }`. Decida pelo `code`, nunca pela `message`. 429 traz `Retry-After`
- Cobrança: `POST /transactions/payment`; o Pix copia e cola é `pix.qrCodeText`. `externalRef` torna a criação idempotente (mesmo pedido devolve 200; dados diferentes, 409)
- Saque (`POST /transactions/withdraw`), pagamento de QR Code (`POST /transactions/pix/qr-payments`) e transferência (`POST /transactions/internal-transfer`): mande `Idempotency-Key`. Num 502, repita com a MESMA chave ou consulte antes. `amount` é o que chega; a tarifa é somada por cima
- Estorno (`POST /transactions/payment/{id}/refund`) não aceita `Idempotency-Key`: num 502, consulte a cobrança antes de repetir
- Libere o pedido no webhook `PAYMENT_PAID`. Saque só está entregue em `WITHDRAW_COMPLETED` (status `CONFIRMED`); 201 com `APPROVED` não é dinheiro entregue
- Webhook: confira `X-Payzu-Signature` (`sha256=` + HMAC-SHA256 em hex de `<X-Payzu-Timestamp>.<corpo cru>`, timestamp em milissegundos), responda 2xx em até 10 segundos e deduplique por `X-Payzu-Delivery`. São até 10 tentativas
- `callbackUrl` na operação exige o segredo de callback da conta (`POST /transactions/callback-secret`)

Quando eu fizer perguntas, responda:
1. Direto ao ponto, com código pronto pra colar
2. Curl primeiro, depois a linguagem que eu pedir, com o cliente HTTP dela ou um cliente gerado da OpenAPI
3. Cite a rota e a seção da doc quando for específico
4. Se eu pedir algo fora do escopo da API, diga e proponha alternativa
5. Nunca mencione rotas administrativas ou internas, hosts/URLs internos, tipos de autenticação internos nem regras de negócio internas: isso não faz parte da API pública

Não invente rotas, campos ou comportamentos que não estejam na OpenAPI. Se não souber, diga "não está documentado, consulte o suporte".

Estou pronto. O que você quer construir?

Esta doc é da API Conta Digital (https://api.hub.payzu.com.br/api/v1, credencial client_id + client_secret trocada por token em POST /oauth/token, valores em centavos). A API Pix (https://api.payzu.processamento.com/v1, valores em reais) e a API Cartões (https://api.payzu.io/v1, mTLS) são outros sistemas, com credenciais próprias. Não misture as APIs na mesma integração.

Endpoints para IAs

URL	O que tem
`/conta-digital/llms.txt`	Índice com o link e a descrição de cada página da Conta Digital.
`/conta-digital/llms-full.txt`	Toda a doc da Conta Digital num arquivo só.
`/llms.txt`	Índice de todos os produtos PayZu.
`/llms-full.txt`	Toda a doc de todos os produtos PayZu.
`/conta-digital-openapi.json`	Especificação OpenAPI 3.1 da Conta Digital: rotas, escopos, campos, exemplos e recusas.
`/api-scalar-conta-digital`	A OpenAPI no Scalar, em versão interativa.
`/api-swagger-conta-digital`	A OpenAPI no Swagger UI.

Por página

Cada página tem uma versão em Markdown. Troque /docs/... por /llms.mdx/docs/.../content.md:

Página	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/withdrawals`	`/llms.mdx/docs/conta-digital/withdrawals/content.md`

No topo de cada página ficam os botões Perguntar à IA, Copiar para LLM (copia o markdown da página) e Ver como Markdown (abre o markdown da página).

Casos de uso

Pergunta rápida no ChatGPT/Claude

Doc da API Conta Digital PayZu: https://docs.payzu.com.br/conta-digital/llms-full.txt
Base URL: https://api.hub.payzu.com.br/api/v1
Token: POST /oauth/token com Basic (client_id:client_secret) e
grant_type=client_credentials. O access_token vale 15 minutos e vai em
Authorization: Bearer. Valores em centavos.

Me mostre um exemplo em Node.js que:
1. Pega o token e pede outro quando a API responde 401 TOKEN_INVALID.
2. Cria uma cobrança Pix de R$ 15,00 ("amount": 1500) com o número do pedido
   em externalRef.
3. Recebe o webhook PAYMENT_PAID e confere o header X-Payzu-Signature: é o
   HMAC-SHA256 de "<X-Payzu-Timestamp>.<corpo cru>" com o segredo do endpoint,
   comparado com o valor depois de "sha256=". Recusa timestamp (em
   milissegundos) com mais de 5 minutos.
4. Ignora webhook repetido pelo header X-Payzu-Delivery.

Cursor / Copilot no editor

Crie um arquivo .cursorrules ou .github/copilot-instructions.md no seu repositório:

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

Regras:
- Base URL: https://api.hub.payzu.com.br/api/v1
- Token: POST /oauth/token com Basic (client_id:client_secret) e
  grant_type=client_credentials. Vale 15 minutos; peça outro no 401 TOKEN_INVALID.
- A conta é a da credencial. Nenhuma rota recebe accountId.
- Valores em centavos, inteiros (1500 = R$ 15,00). Percentuais: 150 = 1,5%.
  Datas em ISO 8601, UTC.
- Listagens: mande o nextCursor da resposta no parâmetro cursor da próxima
  chamada; na última página ele não vem. limit vai de 1 a 100.
- Erro: { message, code, details }. Decida pelo code, nunca pela message.
- Cobrança: repetir com o mesmo externalRef e os mesmos dados devolve a mesma
  cobrança (200); com algum dado diferente, 409 PAYMENT_EXTERNAL_REF_MISMATCH.
- Saque, pagamento de Pix copia e cola e transferência: mande Idempotency-Key.
  Num 502, repita com a mesma chave ou consulte antes.
- Estorno e devolução de depósito não aceitam Idempotency-Key: num 502, consulte
  a cobrança ou o depósito antes de repetir.
- Libere o pedido no webhook PAYMENT_PAID. Saque só chegou ao destino em
  WITHDRAW_COMPLETED (status CONFIRMED).
- Webhook: confira X-Payzu-Signature (HMAC-SHA256 de "<timestamp>.<corpo cru>"),
  responda 2xx em até 10 segundos e ignore repetidos por X-Payzu-Delivery.
- Não invente rotas nem campos: a fonte é https://docs.payzu.com.br/conta-digital-openapi.json

Assistente com a OpenAPI

GPTs com Actions, agentes e geradores de cliente usam https://docs.payzu.com.br/conta-digital-openapi.json direto. A spec traz o escopo de cada rota, exemplos de requisição e resposta e as recusas, com o code de cada uma.