# Z.PAY

> Documentação da API Z.PAY: Pix, checkout (Pix, cartão e boleto), boleto, pagamento de boletos, crypto, cashout, split, transferência entre contas, subcontas, sandbox, canvas e webhooks.
> A documentação (https://zpaysolution.com/docs/) é uma página só por aba. Cada parte tem "Copiar tudo de …" para mandar a uma IA, e o topo tem "Copiar tudo do site".

Base URL: https://zpaysolution.com/api/v1
https://zpayapi.app/api/v2

Autenticação da API de pagamentos (headers em toda requisição de Pix, saque, saldo etc.):
- `client-id`: chave pública (`zpk_…`)
- `client-secret`: segredo (`zsk_…`)

## SDKs e integração com IA

- [SDK Z.PAY](https://zpaysolution.com/docs/#sdk): cliente Node.js 18+, ESM/CommonJS, tipos TypeScript e nenhuma dependência de execução.
- [Referência do SDK em texto para LLMs](https://zpaysolution.com/sdk.txt): instalação, parâmetros, métodos reais, exemplos Pix/LTC/swap e tratamento de erros.
- Instalação principal: `npm install @isnouu/zpay-sdk`; importe `ZPay` de `@isnouu/zpay-sdk`.
- O pacote @isnouu/zpay-sdk 0.1.0 está disponível no npm. [Download alternativo do SDK 0.1.0](https://zpaysolution.com/downloads/zpay-sdk-0.1.0.tgz): instale o arquivo localmente. O arquivo e os novos endpoints precisam estar publicados no site.
- Para JavaScript/TypeScript no servidor, use o SDK npm documentado. Python 3.10+, PHP 8.1+ e Go 1.20+ têm versões v0.1.0 públicas no GitHub. Python instala via pip com URL de release, PHP via Composer VCS e Go via go get. Python/PHP ainda não foram registrados no PyPI/Packagist. Recursos não cobertos usam HTTP.
- Credenciais: `ZPAY_CLIENT_ID` e `ZPAY_CLIENT_SECRET` no backend. O SDK autentica por API key, não por token `zadm_` ou JWT de login.
- Exemplos de métodos: `payments.create`, `payments.get`, `account.stats`, `withdrawals.create`, `subaccounts.create`, `crypto.createPayment` e `crypto.swap`. Leia sdk.txt antes de gerar código; não invente métodos de sandbox ou verificação de webhook.
- Persista `idempotencyKey` antes dos envios Pix e `requestId` antes das operações cripto. O SDK não reenvia automaticamente; `ZPayError.outcomeUnknown` pede consulta da operação original. HTTP 202/pending não confirma pagamento.
- Integrações com ChatGPT, Claude, Cursor, Kiro e Codex devem ler esta referência e https://zpaysolution.com/sdk.txt. Nunca exponha segredos ao navegador nem insira credenciais reais em exemplos.
- [Python via pip](https://github.com/Felix404snow/zpay-sdk-python): `python -m pip install https://github.com/Felix404snow/zpay-sdk-python/releases/download/v0.1.0/zpay_sdk-0.1.0-py3-none-any.whl`. Importe `ZPay` de `zpay`. Métodos em snake_case: `crypto.create_payment`, `bill_payments.preview`; campos de API mantêm camelCase.
- [PHP via Composer](https://github.com/Felix404snow/zpay-sdk-php): `composer config repositories.zpay vcs https://github.com/Felix404snow/zpay-sdk-php`, depois `composer require isnouu/zpay-sdk:^0.1`. Classe `ZPay\\Client`, uso `$client->payments->create($dados)`.
- [Go](https://github.com/Felix404snow/zpay-sdk-go): `go get github.com/Felix404snow/zpay-sdk-go@v0.1.0`. Métodos com contexto: `client.Payments.Create(ctx, dados)`. Use exatamente o module path publicado, sem URL inventada.

## Token da conta (para quem pergunta a uma IA)

Se a pessoa colar um token `zadm_…` ou perguntar "o que o token faz", "token da conta" ou "token das configurações":

O token é gerado em Dashboard → Configurações → Token da conta. Serve para uma IA operar a conta de quem gerou, sem programar. Não é a API key (`zpk_` / `zsk_`) e não é admin da plataforma. Na hora de gerar, o painel mostra o IP da pessoa (Cloudflare) e ela pode adicionar outros. Esses IPs ficam salvos no token. Chamada de outro IP recebe `403` com `ACCOUNT_TOKEN_IP`.

Header: `Authorization: Bearer zadm_…`
Base: https://zpaysolution.com/api/v1/account
https://zpayapi.app/api/v2/account
Docs: https://zpaysolution.com/docs/#account-token

Pode:
- `GET /account` — saldo, username, taxas (entrada, saque, transferência), client-id da API (sem o secret) e URLs de webhook
- `GET /account/fees` — só taxas e limites
- `GET /account/payments?limit=10` — últimos Pix (id, valor, status). Para um dia ou uma hora em Brasília: `?date=2026-09-28`, `?date=2026-09-28&hour=14` (sem date, hour é hoje), ou `?from=2026-09-28T14:00&to=2026-09-28T18:00`. `when=paid` filtra pela hora do pagamento. `status`, `page` e `limit` (até 50). Intervalo máximo 31 dias
- `POST /account/payments` — gera um Pix de teste ou real. Body: `{ "amount": 25, "payerName": "João", "description": "Teste" }`. A resposta traz `copyPaste`
- `GET /account/payments/{id}` — status. Se `paid`, devolve `payer.name`, `payer.document` e `payer.bank`. Se `pending`, devolve `copyPaste`
- `POST /account/webhooks` — cadastra URL HTTPS. Body: `{ "url": "https://..." }`. Máximo 5
- `DELETE /account/webhooks/{id}` — remove a URL
- `POST /account/api-keys/reset` — gera client-id e secret novos e invalida a API key anterior. O secret aparece uma vez
- `POST /account/revoke` — revoga este token

Não pode: sacar, transferir Pix, trocar senha, ver outras contas. A conta pode ter até 3 tokens ao mesmo tempo. Apagar um não recupera. Não passe o token para ninguém além de quem vai usar.

## Guias — Começar

- [Primeira integração](https://zpaysolution.com/docs/#primeira-integracao): Do zero ao primeiro Pix — chave de API, cobrança e webhook
- [SDK JavaScript / TypeScript](https://zpaysolution.com/docs/#sdk): integrar sites e bots pelo backend com `ZPay`, métodos tipados e referências persistentes
- [Conceitos fundamentais](https://zpaysolution.com/docs/#conceitos): Conta, tags, limites, status e produtos da API
- [Chaves de API](https://zpaysolution.com/docs/#auth): Criar e proteger client-id / client-secret
- [Erros e códigos HTTP](https://zpaysolution.com/docs/#erros): 400, 401, 403, 404, 429 e DENIED_ACCESS

## Guias — Tutoriais

- [Criar Pix](https://zpaysolution.com/docs/#criar-pix): QR, copia e cola, confirmação e atalhos para a API Reference
- [Aprovar Pix](https://zpaysolution.com/docs/#payments-approve): Reconciliação de pagamento pendente
- [Checkout hospedado](https://zpaysolution.com/docs/#checkout-guide): Link com Pix, cartão (à vista) e boleto (expira em 30 min)
- [Cartão, boleto e pagar boleto](https://zpaysolution.com/docs/#boleto-guide): receber por cartão/boleto e pagar boletos com o saldo
- [Sandbox](https://zpaysolution.com/docs/#sandbox): testar tudo sem mexer no saldo real
- [Webhooks na prática](https://zpaysolution.com/docs/#webhooks): `payment.created` traz o Pix (copia e cola e QR). `payment.paid` traz nome completo, CPF/CNPJ e banco de quem pagou
- [Prompts para IA](https://zpaysolution.com/docs/#prompts-ia): Prompts prontos para gerar/consultar Pix, checkout, saque e servidor de webhook

## API Reference — Introdução

- [Visão geral](https://zpaysolution.com/docs/#overview): Base URL, auth e formato JSON
- [Autenticação](https://zpaysolution.com/docs/#auth): Headers client-id e client-secret
- [Erros HTTP](https://zpaysolution.com/docs/#erros): Status e códigos comuns

## API Reference — Pix

- [Criar Pix](https://zpaysolution.com/docs/#payments-create): `POST /payments`
- [Consultar Pix](https://zpaysolution.com/docs/#payments-get): `GET /payments/{paymentId}` — traz `paymentMethod` (`pix`, `card`, `boleto`, `crypto`), `card` (`status`, `brand`, `last4`, `installments`, `refusedReason`) e `boleto` (`url`, `barcode`, `digitableLine`, `dueDate`)
- [Nome de quem pagou](https://zpaysolution.com/docs/#payments-payer): `GET /payments/{paymentId}/payer` — nome completo, CPF/CNPJ e banco
- [Aprovar Pix](https://zpaysolution.com/docs/#payments-approve): `POST /payments/{paymentId}/approve`
- [Listar MEDs](https://zpaysolution.com/docs/#meds): `GET /meds`
- [Consultar MED](https://zpaysolution.com/docs/#meds-get): `GET /meds/{id}`
- [Reembolsar Pix](https://zpaysolution.com/docs/#refund): `POST /refund`
- [Listar doações](https://zpaysolution.com/docs/#donations): `GET /donations` — filtre por dia ou hora em Brasília com `date=YYYY-MM-DD`, `hour=0-23`, ou `from` e `to` (máx. 31 dias). `when=paid` usa a hora do pagamento; o padrão é a hora em que o Pix foi criado. O mesmo filtro vale em `GET /withdrawals` (`when=completed`), `GET /crypto/transactions` e `GET /subaccounts/{id}/transactions`
- [Top doações](https://zpaysolution.com/docs/#top-donates): `GET /top-donates`

## API Reference — Checkout

- [Criar checkout](https://zpaysolution.com/docs/#checkouts-create): `POST /checkouts` — `methods` (`["pix","card","boleto"]`, padrão `["pix"]`) (cartão só à vista)
- [Consultar checkout](https://zpaysolution.com/docs/#checkouts-get): `GET /checkouts/{checkoutId}`

## API Reference — Boleto

- [Emitir boleto](https://zpaysolution.com/docs/#boletos-create): `POST /boletos` `{ amount, payerName, payerDocument, payerEmail, payerPhone?, dueDays? (1–30, padrão 3), description?, idempotencyKey? }` → `{ paymentId, status, paymentMethod: "boleto", amount, boleto: { url, barcode, digitableLine, dueDate } }`

## API Reference — Pagar boleto (debita o saldo)

- [Ler boleto](https://zpaysolution.com/docs/#bill-preview): `POST /bill-payments/preview` `{ line, amount? }` → `type` (bancario | arrecadacao), `digitableLine`, `barcode`, `amount`, `amountEditable`, `dueDate`, `bank`, `fee`, `total` (null se amountEditable e sem amount), `overdue`
- [Pagar boleto](https://zpaysolution.com/docs/#bill-create): `POST /bill-payments` `{ line, amount? (só se amountEditable), description?, idempotencyKey? }` → `{ ok, billPayment, balance }`. Exige KYC e telefone. Erros: 400 `BOLETO_INVALID` / `INSUFFICIENT_BALANCE` / `BOLETO_AMOUNT_REQUIRED` / `BOLETO_AMOUNT_FIXED` / `BOLETO_AMOUNT_INVALID` / `CASHOUT_MAX_EXCEEDED`, 403 `KYC_NOT_VERIFIED` / `PHONE_NOT_VERIFIED`, 409 `BOLETO_ALREADY_PAID`, 429 `WITHDRAW_TOO_SOON`
- [Listar](https://zpaysolution.com/docs/#bill-list): `GET /bill-payments?page=1` → `{ items, page, totalPages }`
- [Consultar](https://zpaysolution.com/docs/#bill-get): `GET /bill-payments/{id}`
- Status: `pending` → `paid` (com `receipt.authentication`) ou `rejected` (valor volta ao saldo, motivo em `rejectReason`). Processado em até 1 dia útil (em horário bancário).

## API Reference — Cripto pela Purin

Novos recebimentos são LTC na rede Litecoin, cobrados em BRL, com valor exato de oito casas. Não aplique a tolerância de pagamento parcial da antiga NOWPayments a cobranças Purin. Custos são por conta e precisam estar confirmados no Admin. Os novos endpoints precisam estar publicados na instância utilizada.

- [Receber LTC](https://zpaysolution.com/docs/#crypto-create): POST /payments/crypto { requestId, amount, currency: "brl", payCurrency: "ltc", payerName?, description? }. Retorna paymentId, id da operação, status, payAddress e payAmount. SDK: crypto.createPayment(dados).
- [Swap BRL → USDT BEP20](https://zpaysolution.com/docs/#crypto-usdt): POST /crypto/swap { requestId, amount em BRL, address, confirmNotCoinbase: true, acceptProviderRate: true, totpCode? }. SDK: crypto.swap(dados). Converte saldo BRL; não converte LTC. A cotação é definida pela Purin no envio.
- [Consultar cobrança](https://zpaysolution.com/docs/#crypto-get): GET /payments/crypto/{paymentId}. SDK: crypto.getPayment(paymentId).
- [Saldo LTC e legado separado](https://zpaysolution.com/docs/#crypto-balance): GET /crypto/balance. SDK: crypto.balance(). legacy preserva USDT anterior.
- [Operações Purin](https://zpaysolution.com/docs/#crypto-tx): GET /crypto/purin e GET /crypto/purin/operations/{id}. SDK: crypto.summary() e crypto.operation(id).
- [Saque LTC](https://zpaysolution.com/docs/#crypto-withdraw): POST /crypto/purin/withdraw { requestId, amount em LTC, address Litecoin, totpCode? }. SDK: crypto.withdraw(dados).
- POST /payments/usdt não cria novas cobranças. GET /crypto/transactions e POST /crypto/withdraw ficam para o legado NOWPayments; não use esses endpoints como se fossem novos recebimentos ou saque LTC.
- Timeout, pending ou review não autorizam reenvio nem estorno presumido. Salve id, paymentId e requestId. Para detalhes do SDK e formato de requestId, leia https://zpaysolution.com/sdk.txt.

## API Reference — Transferências

- [Sacar Pix](https://zpaysolution.com/docs/#withdraw-create): `POST /withdraw`
- [Status do saque](https://zpaysolution.com/docs/#withdraw-status): `GET /withdrawals/{id}`
- [Listar saques](https://zpaysolution.com/docs/#withdrawals-list): `GET /withdrawals`
- [Enviar Pix (cashout)](https://zpaysolution.com/docs/#cashout): `POST /cashout`
- [Status do envio](https://zpaysolution.com/docs/#cashout-status): `GET /cashout/{id}`
- [Split conta Z.PAY](https://zpaysolution.com/docs/#split): `POST /split/payment` — outra conta Z.PAY pelo CPF
- [Split chaves Pix e subcontas](https://zpaysolution.com/docs/#split-pix): `POST /split/pix` — até 10 destinos, chave Pix (`pixKey`) ou subconta (`subaccountId`). Subconta sem taxa. Chave Pix: taxa de cash-out × número de chaves, paga pela conta (`feePayer: "account"`, padrão) ou dividida igualmente entre as chaves (`feePayer: "recipients"`, ou `payFee: true` só nas que pagam). A taxa de recebimento vale sobre o total
- [Transferir para conta Z.PAY](https://zpaysolution.com/docs/#internal-transfer): `POST /transfers/internal` — `to` = @username, e-mail, id da conta ou CPF/CNPJ; sem taxa, na hora, só entre contas do mesmo tipo (White↔White, Black↔Black). Conferir o destino: `GET /transfers/internal/recipient?to=…`
- [Consultar split](https://zpaysolution.com/docs/#split-get): `GET /split/payments/{id}`

## API Reference — Subcontas

Saldo separado dentro da API key. Movimentações internas (fund, transfer, payout e fatia de split) não têm taxa. O `{id}` aceita o id Mongo, o `zpayId` (`zsub_…`) ou o `externalId`. Valores em reais (`amount`) ou centavos (`amountCents`). Pix de entrada e envio direto: `subaccountId` em `POST /payments` e `POST /cashout` (também `POST /withdraw`).

- [Criar subconta](https://zpaysolution.com/docs/#subaccounts-create): `POST /subaccounts`
- [Listar subcontas](https://zpaysolution.com/docs/#subaccounts-list): `GET /subaccounts`
- [Consultar subconta](https://zpaysolution.com/docs/#subaccounts-get): `GET /subaccounts/{id}`
- [Extrato da subconta](https://zpaysolution.com/docs/#subaccounts-tx): `GET /subaccounts/{id}/transactions`
- [Enviar da conta principal](https://zpaysolution.com/docs/#subaccounts-fund): `POST /subaccounts/{id}/fund`
- [Transferir entre subcontas](https://zpaysolution.com/docs/#subaccounts-transfer): `POST /subaccounts/{id}/transfer`
- [Repasse para a conta principal](https://zpaysolution.com/docs/#subaccounts-payout): `POST /subaccounts/{id}/payout`
- [Editar subconta](https://zpaysolution.com/docs/#subaccounts-update): `PATCH /subaccounts/{id}` — name, email, externalId, metadata
- [Bloquear / desbloquear](https://zpaysolution.com/docs/#subaccounts-block): `POST /subaccounts/{id}/block` e `/unblock`
- [Apagar subconta](https://zpaysolution.com/docs/#subaccounts-delete): `DELETE /subaccounts/{id}` — o saldo volta para a conta principal antes; recusa com `SUBACCOUNT_BUSY` se houver saque em andamento
- [Saque direto da subconta](https://zpaysolution.com/docs/#subaccounts-withdraw): `POST /subaccounts/{id}/withdraw` — o Pix sai para o CPF/CNPJ da conta e o saldo sai da subconta, sem passar pela conta principal. Entra no extrato como `withdraw`. Se falhar, volta para a subconta (`reversal`).

## API Reference — Sandbox (modo teste)

Base: https://zpaysolution.com/api/v1/sandbox
https://zpayapi.app/api/v2/sandbox — mesmas credenciais de API. **Nada no sandbox toca o saldo real**: usa um saldo virtual separado, nenhum Pix, cartão ou boleto é cobrado e nada entra no extrato. Ids começam com `sbx_`.

- [Como funciona](https://zpaysolution.com/docs/#sandbox): rotas, cartões de teste e regras de webhook
- [Saldo virtual](https://zpaysolution.com/docs/#sandbox-balance): `GET /sandbox/balance` → `{ sandbox: true, balance, currency: "BRL" }`
- [Criar Pix de teste](https://zpaysolution.com/docs/#sandbox-payments): `POST /sandbox/payments` (mesmos campos de /payments + `webhookUrl`). copyPaste começa com `ZPAYSANDBOX`
- [Listar / consultar](https://zpaysolution.com/docs/#sandbox-payments-get): `GET /sandbox/payments`, `GET /sandbox/payments/{id}`
- [Simular pagamento](https://zpaysolution.com/docs/#sandbox-payments-simulate): `POST /sandbox/payments/{id}/simulate` com `{ "status": "paid" | "expired" | "failed" }`
- [Checkout de teste](https://zpaysolution.com/docs/#sandbox-checkouts): `POST /sandbox/checkouts` (aceita `methods` e `maxInstallments`). Link `/checkout/sbx_…?token=…` com faixa "MODO TESTE"
- [Cartões de teste](https://zpaysolution.com/docs/#sandbox-test-cards): `GET /sandbox/test-cards`. 4000 0000 0000 0002 e 5555 5555 5555 4444 aprovam; 4000 0000 0000 0069 recusa (saldo insuficiente); 4000 0000 0000 0119 fica em análise e aprova em ~10 s. Outro número → 400 `SANDBOX_TEST_CARD_ONLY`
- [Boleto de teste](https://zpaysolution.com/docs/#sandbox-boletos): `POST /sandbox/boletos` — boleto fictício, linha marcada como teste
- [Pagar boleto (teste)](https://zpaysolution.com/docs/#sandbox-bill-payments): `POST /sandbox/bill-payments` debita o saldo virtual; `POST /sandbox/bill-payments/{id}/simulate` com `{ "status": "paid" | "rejected" }`
- [Saque de teste](https://zpaysolution.com/docs/#sandbox-withdraw): `POST /sandbox/withdraw` `{ amount, pixKey, pixKeyType }`
- [Segredo do webhook](https://zpaysolution.com/docs/#sandbox-webhook-secret): `GET /sandbox/webhook-secret`
- [Zerar dados](https://zpaysolution.com/docs/#sandbox-reset): `POST /sandbox/reset`
- Webhooks de sandbox: só vão para o `webhookUrl` enviado na criação (nunca para as URLs do Dashboard). Header `X-ZPay-Sandbox: 1`, evento com prefixo `sandbox.` (ex.: `sandbox.payment.paid`), corpo com `livemode: false`, assinados com um segredo SEPARADO. No endpoint de produção, ignore eventos com `livemode: false`.

## API Reference — Conta

- [Token da conta](https://zpaysolution.com/docs/#account-token): como gerar em Configurações e colar numa IA. `GET /api/v1/account` com `Authorization: Bearer zadm_…`
- [Taxas da conta](https://zpaysolution.com/docs/#fees): `GET /fees` — entrada, saque, transferência e limites em vigor
- [Estatísticas](https://zpaysolution.com/docs/#stats): `GET /stats`
- [Canvas (imagem PNG)](https://zpaysolution.com/docs/#canvas): `GET /canvas?type=daily|weekly|monthly|total`

## API Reference — Webhooks

- [Receber eventos](https://zpaysolution.com/docs/#webhooks): Cadastro no Dashboard. Cada URL tem um segredo `zwhsec_…`. Assinatura HMAC-SHA256 de `{timestamp}.{body}` nos headers `X-ZPAY-Timestamp` e `X-ZPAY-Signature`. Recuse se o horário tiver mais de 5 minutos.
- Idempotência: `idempotencyKey` (ou `reference` / `externalId`) em `POST /payments`, `POST /cashout` e `POST /withdraw`. A mesma chave devolve a mesma operação (`replayed: true`). Consulte por esse valor em `GET /payments/{id}`, `GET /cashout/{id}` e `GET /withdrawals/{id}`.
- `subaccountId` na criação do Pix credita o líquido na subconta. No envio e no saque, o valor sai dela. Se o envio falhar, volta para a mesma subconta.
- `endToEnd` é o identificador do Pix no Banco Central. Vem na consulta do pagamento, no webhook `payment.paid` (`data.endToEnd`) e na consulta do envio.
- Eventos além da cobrança: `withdraw.created|completed|failed|cancelled`, `cashout.*`, `refund.*`, `med.opened` e `med.closed`. O aviso de saque/envio não traz a chave Pix, só `pixKeyType`.
- `payment.paid` cobre Pix, cartão e boleto: veja `data.paymentMethod` (e `data.card` / `data.boleto`).
- Pagamento de boleto com o saldo: `bill_payment.paid` (traz `receipt`) e `bill_payment.rejected` (traz `rejectReason`; o valor voltou para o saldo).

## Links

- Docs: https://zpaysolution.com/docs/
- Dashboard: https://zpaysolution.com/login/
- FAQ: https://zpaysolution.com/faq/