API Pix v1

Integre cobrança Pix sem adivinhação.

Sua loja, ERP, CRM ou SaaS cria cobranças e carnês, manda o link ou o QR ao pagador, e recebe a confirmação por webhook. Tudo o que está nesta página é o que a API faz hoje — campos, erros e limites conferidos contra o código.

REST + JSON Idempotente Webhooks assinados

Começar agora OpenAPI (JSON) Versão em texto

Contrato canônico

Base: https://api.pagueo.com.br/api/v1
Formato: application/json
Dinheiro: amountCents (inteiro)
Datas: ISO 8601, UTC
Credencial: Bearer vk_test_… / vk_live_…

Valores são inteiros em centavos. Nunca use ponto flutuante para dinheiro. Campos desconhecidos são recusados com 400.

Instrução para IA e agentes de código

Use /llms.txt (esta documentação em markdown) e https://api.pagueo.com.br/api/docs-json (OpenAPI 3) como fonte de verdade. Envie somente os campos descritos; o ambiente vem da chave, não do corpo. Mantenha a mesma Idempotency-Key em retries. Considere uma cobrança paga apenas quando status for PAID em GET /charges/:id ou num webhook charge.paid com assinatura válida.

Primeira integração

Comece em 5 minutos

Crie uma chave de TESTE no painel, guarde-a no servidor, crie uma cobrança, simule o pagamento e veja o status virar PAID.

Crie uma chave de API

Em Desenvolvedores, crie uma chave vk_test_ com os escopos charges:write e webhooks:write. O segredo aparece uma única vez.

Abrir Desenvolvedores

Crie a cobrança

POST /charges com amountCents, description, externalId (o id do seu pedido) e uma Idempotency-Key estável.

Simule e confirme

Em TEST, POST /charges/:id/simulate-payment paga a cobrança pelo mesmo caminho da produção. Libere o pedido só com status PAID.

curl --request POST 'https://api.pagueo.com.br/api/v1/charges' \
  --header 'Authorization: Bearer vk_test_sua_chave' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: pedido-1033' \
  --data '{
    "amountCents": 14990,
    "description": "Pedido #1033",
    "externalId": "pedido-1033",
    "expiresInSeconds": 3600
  }'

Em TEST o Pix não é pagável de verdade e qrCodeUrl vem null — é o simulate-payment que exercita o resto do caminho, inclusive o webhook.

Fluxo real

Do Pix criado ao pagamento confirmado

A PAGUEO conversa com o provedor de liquidação; sua aplicação conversa só com a PAGUEO. Duas formas de saber que entrou: o webhook assinado, ou a consulta.

Sua aplicaçãoPOST /charges

PAGUEOQR + copia e cola + link

PagadorPaga o Pix

PAGUEOConfirma com o provedor

Sua aplicaçãowebhook charge.paid ou GET /charges/:id = PAID

Exiba só o que veio na resposta

qrCodeUrl · pixCopyPaste · publicUrl

A criação devolve PENDING. Exibir um QR não é confirmação de pagamento.

Confirmação no backend

charge.paid (assinado) ou GET /charges/:id

O webhook chega em segundos. Se preferir certeza dupla, ao receber o evento consulte a cobrança antes de liberar.

Credenciais

Autenticação e escopos

Toda chamada privada usa Bearer token. A conta é a da chave: não existe tenantId na API, e o ambiente (TEST ou LIVE) também vem da chave.

Chave de API, só no servidor

Authorization: Bearer vk_live_…

Nunca em frontend, aplicativo ou repositório. Uma chave vazada se revoga no painel e se recria.

Uma chave, uma conta

vk_test_… cria em TEST · vk_live_… em LIVE

Quem opera várias lojas tem uma chave por loja. O campo environment no corpo é aceito por compatibilidade e ignorado.

EscopoTipoPadrãoPermite

charges:readleiturasim

Consultar cobranças, carnês e a linha do tempo de cada uma; enviar a cobrança por e-mail.

charges:writeescritanão

Criar cobranças e carnês, baixar, conferir no provedor e simular pagamento (TEST).

customers:readleiturasim

Listar e consultar clientes (pagadores).

customers:writeescritanão

Cadastrar e editar clientes.

webhooks:readleituranão

Listar os endpoints de webhook e o histórico de entregas.

webhooks:writeescritanão

Cadastrar e remover endpoints, girar o segredo e reenviar entregas.

balance:readleituranão

Ler o saldo da conta.

transfers:readleituranão

Listar e consultar Pix enviados e pedidos de saque.

transfers:writeescritanão

Reservado ao painel: envio de Pix e pedido de saque com chave de API respondem 403.

bills:readleituranão

Consultar contas pagas e ler um código de barras.

bills:writeescritanão

Reservado ao painel: pagar conta com chave de API responde 403.

"Padrão: sim" é o que uma chave recebe quando POST /api-keys vem sem scopes. Peça só o que a integração usa; escopo faltando responde 403 Escopo X não concedido.

Endpoint principal

Cobranças Pix

Uma cobrança gera QR Code, Pix copia e cola e uma página pública para compartilhar por WhatsApp, e-mail ou checkout.

POST/chargescharges:write

CampoTipoObrigatórioDescrição

amountCentsintegersim

Valor em centavos de BRL, de 1 a 100.000.000 (R$ 0,01 a R$ 1.000.000,00). Ex.: 14990 = R$ 149,90.

descriptionstring ≤ 140sim

O que está sendo cobrado; aparece na cobrança e para o pagador. Obrigatória, exceto quando vier chargeItemId. Descrição que indique atividade proibida (apostas, armas, drogas, pirâmide…) é recusada com 400 PROHIBITED_BUSINESS_CATEGORY.

externalIdstring ≤ 100não

O id do pedido no SEU sistema. Volta em toda resposta e em todo webhook: é a sua chave de conciliação.

customerIdstringnão

Cliente cadastrado na conta (POST /customers). Nome, documento e e-mail dele vão ao provedor. Inexistente responde 404.

expiresInSecondsintegernão

Validade do QR, de 60 a 2.592.000 segundos (30 dias). Sem o campo: 3600 (1 hora).

payerNamestring ≤ 120não

Nome do pagador quando não há customerId.

payerDocumentstring ≤ 20não

CPF ou CNPJ do pagador quando não há customerId. Máscara é aceita e descartada.

chargeItemIdstringnão

Item do catálogo da conta (cadastrado no painel). Dispensa description. O VALOR não vem do item: mande amountCents sempre.

environmentTEST | LIVEnão

Aceito por compatibilidade e IGNORADO: o ambiente vem da credencial. vk_test_ cria em TEST; vk_live_ cria em LIVE.

Resposta 201

A mesma forma volta em GET /charges/:id e dentro de todo webhook. Guarde o id junto do pedido.

{
  "id": "cmtyv7fek000bpc018ulijzjg",
  "status": "PENDING",
  "environment": "TEST",
  "amountCents": 14990,
  "currency": "BRL",
  "description": "Pedido #1033",
  "reference": null,
  "externalId": "pedido-1033",
  "pixCopyPaste": "00020126580014br.gov.bcb.pix…",
  "qrCodeUrl": "data:image/png;base64,…",
  "expiresAt": "2026-09-12T22:00:00.000Z",
  "paidAt": null,
  "feeCents": null,
  "netAmountCents": null,
  "publicUrl": "https://pagueo.com.br/p/<token>",
  "customer": null,
  "chargeItem": null,
  "installmentNumber": null,
  "paymentPlanId": null,
  "createdAt": "2026-09-12T21:00:00.000Z"
}

CampoTipo—Significado

idstringnão

Identificador da cobrança. Guarde junto do pedido.

statusenumnão

Ver a tabela de status. Liberar o pedido só em PAID.

environmentTEST | LIVEnão

Em TEST o Pix NÃO é pagável e qrCodeUrl vem null; use simulate-payment.

pixCopyPastestring | nullnão

O código Pix copia e cola (BR Code).

qrCodeUrlstring | nullnão

A imagem do QR pronta para <img src>: data URI em produção; null em TEST.

publicUrlstringnão

Página de pagamento hospedada pela PAGUEO, para mandar por WhatsApp ou e-mail.

expiresAtISO 8601 | nullnão

Quando o QR deixa de valer.

paidAtISO 8601 | nullnão

Quando o provedor confirmou o pagamento.

feeCents / netAmountCentsinteger | nullnão

Tarifa da PAGUEO e valor líquido. null até a liquidação; 0 é tarifa zero.

customerobjeto | nullnão

{ id, name, email, phone } quando a cobrança tem cliente.

chargeItemobjeto | nullnão

{ id, name, category } quando veio do catálogo. null em tudo que entra pela API sem chargeItemId.

installmentNumber / paymentPlanIdinteger | string | nullnão

Preenchidos quando a cobrança é parcela de um carnê.

Status

Status——Significado

CREATED

Registrada, sem o QR confirmado pelo provedor ainda. Passageiro.

PENDING

QR emitido, aguardando o pagador. É o status normal logo depois de criar.

PAID

Pagamento confirmado pelo provedor. SÓ AQUI o pedido pode ser liberado.

EXPIRED

Venceu sem pagamento. Não volta: crie outra cobrança.

CANCELLED

Baixada por você (POST /charges/:id/cancel) ou junto do carnê.

REFUNDED

Devolvida ao pagador. Reservado para conciliação: hoje nenhuma rota da API devolve.

FAILED

O provedor recusou a emissão. Nada foi cobrado.

Status não é booleano. Uma criação bem-sucedida devolve PENDING. Só marque o pedido como pago em PAID.

Baixa

POST /charges/:id/cancel

Cancela no provedor e aqui. Só CREATED ou PENDING; cobrança paga responde 409. Corpo opcional: { reason }.

Linha do tempo

GET /charges/:id/events

Cada transição com origem, payload e horário — criação, webhook, conciliação, baixa.

Conferir agora

POST /charges/:id/reconcile

Pergunta ao provedor o status real (LIVE). Para quando o pagador diz que pagou e a cobrança segue PENDING.

Simular pagamento

POST /charges/:id/simulate-payment

Só TEST. Marca como paga pelo mesmo caminho da produção: tarifa, eventos e webhook charge.paid.

Cobrança parcelada

Carnê Pix

O carnê é N cobranças com vencimento (Boleto Pix), emitidas de uma vez. Cada parcela continua pagável depois de vencer, com multa e juros calculados pelo provedor — como um boleto.

POST/charges/planscharges:write

CampoTipoObrigatórioDescrição

titlestring ≤ 140sim

Nome do carnê. Cada parcela sai como "<title> - parcela N/T".

installmentAmountCentsintegersim

Valor de CADA parcela, em centavos (1 a 100.000.000).

installmentCountintegersim

Quantidade de parcelas, de 1 a 60. Uma cobrança com vencimento por parcela, todas emitidas de uma vez.

firstDueDateYYYY-MM-DDsim

Vencimento da primeira parcela; as seguintes vencem no mesmo dia dos meses seguintes.

descriptionstring ≤ 140não

Texto livre sobre o contrato ou plano.

customerIdstringnão

Obrigatório NA PRÁTICA: cobrança com vencimento exige CPF/CNPJ do pagador (regra do arranjo Pix), e é do cliente cadastrado que ele vem. Sem cliente com documento, o provedor recusa.

environmentTEST | LIVEnão

Aceito e ignorado: o ambiente vem da credencial.

O que volta

id, status (ACTIVE, COMPLETED, CANCELLED), totalAmountCents e publicUrl — a página do carnê inteiro.
installments[]: number, amountCents, dueDate, status e a charge de cada parcela, com QR, copia e cola e link próprios.
A cobrança com vencimento exige CPF/CNPJ do pagador: cadastre o cliente com document antes.
Um carnê faz uma chamada ao provedor por parcela e demora alguns segundos: mande Idempotency-Key para um retry não criar dois carnês.

{
  "title": "Mensalidade Plano Pro",
  "installmentAmountCents": 12500,
  "installmentCount": 12,
  "firstDueDate": "2026-10-10",
  "customerId": "cmtx…cliente"
}

POST/charges/plans/:id/cancelcharges:write

Baixa o carnê no provedor e cancela todas as parcelas ainda PENDING. Parcelas pagas continuam no histórico.

Pagadores

Clientes

Cadastre quem paga uma vez e reaproveite em cobranças e carnês. É do cadastro que saem nome, documento e e-mail enviados ao provedor.

POST/customerscustomers:write

CampoTipoObrigatórioDescrição

namestring 3–120sim

Nome completo, como no documento.

documentstring ≤ 20sim

CPF ou CNPJ. Máscara é aceita e descartada. É o que permite emitir carnê para este cliente.

phonestring ≤ 30sim

Telefone com DDD. Aceita máscara e o 55 na frente.

emaile-mail ≤ 160não

Para onde a cobrança pode ser enviada por e-mail.

externalCodestring ≤ 100não

O código deste cliente no seu sistema.

identityDocumentstring ≤ 40não

RG ou outro documento de identidade.

genderFEMALE | MALE | OTHER | UNDISCLOSEDnão

Opcional.

addressStreet, addressNumber, addressComplement, addressNeighborhood, addressCitystringnão

Endereço, campo a campo. Todos opcionais.

addressStateUF (2 letras)não

Sigla do estado.

addressPostalCodestring ≤ 9não

CEP, com ou sem hífen.

Regras

Documento duplicado na mesma conta responde 409. Use GET /customers?q= antes, ou guarde o id pelo seu externalCode.
GET /customers devolve podeReceberCarne: true quando há documento.
PATCH /customers/:id aceita qualquer subconjunto dos campos.

{
  "name": "Maria da Silva Souza",
  "document": "12345678901",
  "phone": "11999990000",
  "email": "maria@empresa.com.br",
  "externalCode": "cliente-1033"
}

Eventos

Seus webhooks: a PAGUEO avisa o seu sistema

Cadastre um endereço https e receba um POST assinado a cada evento da conta. É o que faz o seu sistema dar baixa sozinho.

POST/webhook-endpointswebhooks:write

CampoTipoObrigatórioDescrição

urlhttps, 8–500sim

Endereço PÚBLICO que vai receber os POSTs. Só https; endereços internos ou privados são recusados; redirecionamentos não são seguidos.

descriptionstring ≤ 120não

Só para você reconhecer depois (ex.: "ERP produção").

eventsstring[]não

Quais eventos assinar. Em branco, assina todos. Valores: charge.paid, charge.expired, charge.cancelled, charge.refunded.

Eventos

charge.paid — O provedor confirmou o pagamento. data.charge.status é PAID e paidAt está preenchido.
charge.expired — A cobrança venceu sem pagamento.
charge.cancelled — A cobrança foi baixada.
charge.refunded — A cobrança foi devolvida (reservado; ver o status REFUNDED).
A resposta do cadastro traz o secret (whsec_…) uma única vez. Perdeu? POST /webhook-endpoints/:id/rotate-secret.
Também dá para cadastrar pelo painel, em Desenvolvedores → Webhooks.

{
  "url": "https://seusistema.com.br/webhooks/pagueo",
  "description": "ERP produção",
  "events": [
    "charge.paid",
    "charge.expired"
  ]
}

PagadorPaga o Pix

PAGUEOConfirma com o provedor

PAGUEOPOST assinado no seu endpoint

Sua aplicaçãoConfere a assinatura e dá baixa

O que chega

POST com Content-Type: application/json, cabeçalho x-pagueo-signature: t=<unix>,v1=<hex>, mais x-pagueo-event-id, x-pagueo-event-type e x-pagueo-delivery-attempt. O data.charge tem a mesma forma de GET /charges/:id.

{
  "id": "evt_charge_paid_cmtyv7fek000bpc018ulijzjg",
  "type": "charge.paid",
  "createdAt": "2026-09-12T21:05:10.000Z",
  "data": {
    "charge": {
      "id": "cmtyv7fek000bpc018ulijzjg",
      "status": "PAID",
      "environment": "TEST",
      "amountCents": 14990,
      "currency": "BRL",
      "description": "Pedido #1033",
      "reference": null,
      "externalId": "pedido-1033",
      "pixCopyPaste": "00020126580014br.gov.bcb.pix…",
      "qrCodeUrl": "data:image/png;base64,…",
      "expiresAt": "2026-09-12T22:00:00.000Z",
      "paidAt": "2026-09-12T21:05:08.000Z",
      "feeCents": 178,
      "netAmountCents": 14812,
      "publicUrl": "https://pagueo.com.br/p/<token>",
      "customer": null,
      "chargeItem": null,
      "installmentNumber": null,
      "paymentPlanId": null,
      "createdAt": "2026-09-12T21:00:00.000Z"
    }
  }
}

# Cabeçalhos que chegam no seu endpoint:
x-pagueo-signature: t=1789246571,v1=9f2c…   # HMAC-SHA256(secret, "<t>.<corpo cru>") em hex
x-pagueo-event-id: evt_charge_paid_cmtyv7fek000bpc018ulijzjg
x-pagueo-event-type: charge.paid
x-pagueo-delivery-attempt: 1
user-agent: PAGUEO-Webhooks/1

# Reproduzir a assinatura no terminal (corpo cru em body.json):
printf '%s.%s' "$T" "$(cat body.json)" | openssl dgst -sha256 -hmac "$PAGUEO_WEBHOOK_SECRET"

Assinatura sobre o corpo CRU

HMAC-SHA256(secret, "<t>.<corpo cru>") em hex, comparado em tempo constante. Recuse se |agora − t| passar de 300 s. Reserializar o JSON muda espaços e derruba a assinatura.

Responda 2xx só depois de gravar

Qualquer outra resposta, ou demora, vira reentrega com estas esperas em minutos: 0, 1, 5, 30, 120, 360, 1440 (7 tentativas em 24 h). Depois, DEAD_LETTER no histórico, com reenvio manual.

Trate x-pagueo-event-id como chave de idempotência

O mesmo evento redescoberto por dois caminhos (webhook do provedor e conciliação) gera um id só. Seu sistema recebe uma vez — ou a repetição com o mesmo id.

Só https, sem destino privado, sem redirecionamento

Endereços internos são recusados no cadastro e a entrega não segue redirect. Em TEST, simulate-payment dispara charge.paid igual à produção — é assim que se testa o endpoint.

Histórico de entregas

GET /webhook-endpoints/deliveries

As 50 entregas mais recentes, com as últimas 5 tentativas de cada: status HTTP, latência e erro. É a primeira coisa a olhar quando 'não chegou'.

Reenviar

POST /webhook-endpoints/deliveries/:id/resend

Reenvia agora — inclusive entregas já em DEAD_LETTER.

Saldo e saída de dinheiro

Pela API se lê; quem move é o painel

O saldo da conta, os Pix enviados e as contas pagas são consultáveis pela API. Enviar Pix, pedir saque e pagar conta exigem senha de transferência e código por e-mail — e por isso são operações do painel.

Leitura

GET /charges/balance · /charges/transfers · /charges/bill-payments

Saldo (balance:read); Pix enviados com status, quem recebeu e liquidação (transfers:read); contas pagas (bills:read).

Escrita: só sessão

POST /charges/transfers · /withdrawals · /bill-payments

Com chave de API respondem 403 — por desenho. Uma chave vazada não pode tirar dinheiro da conta.

GET /charges/transfers/:id confere no banco na hora.

Enquanto um Pix enviado estiver PROCESSING, a consulta pergunta ao provedor e devolve o status real — e, depois da liquidação, o nome, o documento mascarado e a instituição de quem recebeu. Teto: 60 por minuto.

Comportamento

Erros, retries e idempotência

O corpo de erro é o do NestJS: statusCode, message e, em alguns casos, um code estável. Não existe envelope error.

Formato real

// 401 — sem credencial ou chave inválida
{ "statusCode": 401, "message": "Sessao invalida.", "code": "SESSION_EXPIRED" }

// 400 — validação: message é uma LISTA
{ "statusCode": 400, "message": ["amountCents must be an integer number", "property foo should not exist"], "error": "Bad Request" }

// 403 — escopo
{ "statusCode": 403, "message": "Escopo charges:write não concedido.", "error": "Forbidden" }

400Corpo inválido

Campo faltando, tipo errado ou campo DESCONHECIDO — a API recusa propriedades que não existem no contrato. message vem como lista de frases, uma por problema. Corrija e repita com a mesma Idempotency-Key.

400Categoria proibida · PROHIBITED_BUSINESS_CATEGORY

A descrição indica atividade que a PAGUEO não cobra (apostas, armas, drogas, pirâmide…). O corpo traz category. Não repita sem mudar o produto.

401Sem credencial, ou credencial inválida · SESSION_EXPIRED

Falta o Authorization, ou a chave é inválida ou foi revogada. O code é o mesmo da sessão do painel: com chave de API não há o que renovar — confira a chave. Nunca tente outra conta.

403Escopo ou operação não permitida

"Escopo X não concedido": crie a chave com o escopo certo. Ou a rota só aceita sessão do painel (toda saída de dinheiro).

404Não encontrado

O id não é desta conta ou não existe. Rota inexistente responde { "message": "Cannot GET /api/v1/…", "statusCode": 404 }.

409Conflito

Idempotency-Key reutilizada com corpo diferente, ou a mesma requisição ainda em andamento; ou transição impossível (baixar cobrança paga, cliente com documento já cadastrado).

429Teto de requisições

Espere e repita com backoff exponencial, mantendo a mesma Idempotency-Key para a mesma operação.

503Provedor ou função indisponível

O provedor de liquidação não respondeu, ou a função está desligada na plataforma. A operação PODE ter sido recebida: consulte (GET) antes de criar de novo.

Idempotency-Key

Texto seu, estável por operação (o id do pedido serve). Mesma chave + mesmo corpo em 24 h devolve a MESMA resposta sem criar de novo. Mesma chave + corpo diferente: 409. Chave ainda em andamento: 409 (a reserva expira em 5 min se o processo morrer). Em erro de rede, repita com a mesma chave em vez de gerar outra.

Erro de rede é estado desconhecido

A cobrança pode ter sido criada. Antes de criar outra, repita com a mesma Idempotency-Key ou procure por externalId em GET /charges.

Tetos

GET /public/*: 60 por minuto, por origem · GET /charges/transfers/:id: 60 por minuto, por usuário · POST /charges/:id/send-email: 30 por hora, por usuário · POST /charges/transfers/key-lookup: 30 por minuto, por usuário. Fora disso não há teto fixo — e mesmo assim trate 429 com backoff.

Mapa da API

Referência de endpoints

Caminhos relativos a https://api.pagueo.com.br/api/v1. Pesquise por objetivo, método, escopo ou caminho. Listagens devolvem { data: [...] } com os 100 itens mais recentes.

Cobranças Pix

MétodoEndpointAcessoO que faz

POST/chargescharges:writeCria uma cobrança Pix imediata: QR, copia e cola e link público. Aceita Idempotency-Key.

GET/chargescharges:readAs 100 cobranças mais recentes da conta, da mais nova para a mais antiga. Sem paginação.

GET/charges/:idcharges:readUma cobrança. É ESTA consulta que decide se o pedido pode ser liberado (status PAID).

GET/charges/:id/eventscharges:readLinha do tempo: cada transição de status, com origem, payload e horário.

POST/charges/:id/cancelcharges:writeBaixa uma cobrança CREATED ou PENDING, no provedor e aqui. Corpo opcional: { "reason" }.

POST/charges/:id/reconcilecharges:writePergunta ao provedor o status real agora (cobrança LIVE). Para quando o pagador diz que pagou e a cobrança segue PENDING.

POST/charges/:id/simulate-paymentcharges:writeSó TEST: marca a cobrança como paga pelo MESMO caminho da produção — tarifa, eventos e webhook charge.paid incluídos.

POST/charges/:id/send-emailcharges:readEnvia a cobrança por e-mail ao cliente. Corpo opcional: { "email" }. Teto: 30 por hora.

GET/public/charges/:tokenpúblicoO que a página de pagamento mostra (dados do pagador mascarados). Teto: 60 por minuto.

Carnês (Boleto Pix parcelado)

MétodoEndpointAcessoO que faz

POST/charges/planscharges:writeCria o carnê inteiro: uma cobrança com vencimento por parcela, todas emitidas de uma vez. Aceita Idempotency-Key.

GET/charges/planscharges:readCarnês da conta, com as parcelas e a cobrança de cada uma.

POST/charges/plans/:id/cancelcharges:writeBaixa o carnê e todas as parcelas ainda abertas. Parcelas pagas ficam no histórico.

GET/public/plans/:tokenpúblicoA página do carnê: parcelas, vencimentos e status.

Clientes (pagadores)

MétodoEndpointAcessoO que faz

GET/customers?q=customers:readAté 100 clientes. q busca por nome e e-mail; com 3 ou mais dígitos, também por documento e telefone.

GET/customers/:idcustomers:readUm cliente.

POST/customerscustomers:writeCadastra um pagador. name, document e phone são obrigatórios.

PATCH/customers/:idcustomers:writeEdita o cadastro; todos os campos são opcionais aqui.

Seus webhooks (a PAGUEO avisa o seu sistema)

MétodoEndpointAcessoO que faz

POST/webhook-endpointswebhooks:writeCadastra um endereço https. A resposta traz o secret (whsec_…) UMA única vez.

GET/webhook-endpointswebhooks:readEndpoints cadastrados, sem o segredo.

DELETE/webhook-endpoints/:idwebhooks:writeRemove o endpoint; entregas pendentes param.

POST/webhook-endpoints/:id/rotate-secretwebhooks:writeGira o segredo. O anterior para de valer no mesmo instante.

GET/webhook-endpoints/deliveries?endpointId=webhooks:readAs 50 entregas mais recentes, com as últimas 5 tentativas de cada (status HTTP, latência, erro).

POST/webhook-endpoints/deliveries/:id/resendwebhooks:writeReenvia uma entrega agora — inclusive as que já viraram DEAD_LETTER.

Saldo e saída de dinheiro (somente leitura pela API)

MétodoEndpointAcessoO que faz

GET/charges/balancebalance:readSaldo da conta no provedor.

GET/charges/withdrawals/balancetransfers:readSaldo disponível para sacar, já descontados os pedidos em aberto.

GET/charges/transferstransfers:readOs 100 Pix enviados mais recentes: status, quem recebeu, liquidação e motivo quando não realizado.

GET/charges/transfers/:idtransfers:readUm Pix enviado, conferido no banco na hora enquanto estiver PROCESSING. Teto: 60 por minuto.

GET/charges/withdrawalstransfers:readPedidos de saque da conta.

GET/charges/bill-paymentsbills:readContas (boletos) pagas com o saldo.

POST/charges/bill-payments/detailsbills:readLê um código de barras ou linha digitável: beneficiário, vencimento, valor final e se pode ser pago.

POST/charges/transfers · /charges/withdrawals · /charges/bill-paymentssessão do painelMovimentam dinheiro e exigem senha de transferência e código por e-mail. Chave de API responde 403 — por desenho, não por falta.

Painel (sessão) — não use na integração

MétodoEndpointAcessoO que faz

POST/auth/loginsessãoLogin do painel: senha e depois código por e-mail (/auth/verify-otp). Integração usa chave de API, nunca sessão.

GET/auth/mesessãoUsuário, conta ativa e permissões.

GET/tenantssessãoAs contas do usuário e a ativa. Uma chave de API pertence a UMA conta.

POST/api-keyssessãoCria uma chave (TEST ou LIVE) com escopos; o segredo aparece uma vez. Mais simples pelo painel, em Desenvolvedores.

POST/api-keys/:id/revoke · /api-keys/:id/rotatesessãoRevoga (para de valer, fica na lista) ou gira o segredo (o anterior para de valer).

DELETE/api-keys/:idsessãoExclui a chave de vez, ativa ou revogada. A auditoria guarda nome, prefixo e ambiente.

O contrato completo, com esquemas de requisição e resposta: https://api.pagueo.com.br/api/docs-json (JSON) · interface navegável.

Checklist de produção

Segurança que precisa estar no código

Antes de trocar para a chave de produção, confira estes pontos no seu backend.

Chave só no servidor

Variável de ambiente ou cofre. Nunca em frontend, aplicativo ou repositório. Vazou: revogue no painel e crie outra.

Webhook conferido

Assinatura validada sobre o corpo cru, tolerância de tempo, x-pagueo-event-id como chave de idempotência.

Pago é PAID

Nunca marque um pedido como pago a partir do navegador ou de um corpo que não veio assinado da PAGUEO.

Idempotência

Idempotency-Key estável por pedido; retry com a mesma chave; consulta antes de criar de novo.

Escopo mínimo

Uma chave por sistema, só com os escopos que ele usa. Leitura não precisa de charges:write.

Rastros

Guarde id, externalId, status e a hora de cada resposta: é o que permite conciliar e abrir um chamado com fatos.