Integração com a API
Configure ambientes, headers, formatos e interpretação das respostas da API.
URLs dos ambientes
Sandbox
https://api.pagou.cloud
Testes da integração com a conta de Sandbox.
Produção
https://api.pagou.com.br
Operações reais da conta de produção.
Os caminhos das operações começam com /v1. Use a URL base da tabela e a chave correspondente. Os exemplos deste conjunto não executam chamadas automaticamente.
Variáveis dos exemplos
export PAGOU_BASE_URL='https://api.pagou.cloud'
# PAGOU_API_KEY deve estar configurada no ambiente do seu backend.Configure PAGOU_API_KEY pelo mecanismo de segredos da sua aplicação. Ao mudar para produção, troque explicitamente URL e chave.
Cabeçalhos
X-API-KEY
Enviar em todas as chamadas autenticadas da API pública.
Content-Type: application/json
Enviar quando a requisição tiver um corpo JSON.
User-Agent
Identificar a integração, por exemplo MinhaIntegracao/1.0. Os exemplos incluem esse header.
Envie números JSON com ponto decimal. Mantenha documentos, CEPs, contas e identificadores como strings para preservar zeros à esquerda.
Como interpretar uma resposta
200
Ler o JSON da consulta ou confirmar recebimento de webhook.
201
Guardar o identificador do recurso criado. Isso não confirma pagamento.
204
A resposta não tem corpo; não chamar response.json(). Confira a etapa posterior indicada na operação.
400 / 401 / 404 / 409
Tratar conforme a causa e a página do endpoint.
429
Respeitar Retry-After quando fornecido e reduzir a frequência das chamadas.
5xx ou timeout
Avaliar se o resultado está indeterminado antes de repetir uma alteração financeira.
Não presuma um único formato de erro. Algumas respostas trazem error como string, outras message, e validações podem incluir errors. Veja Erros e recuperação.
Datas, valores e exemplos
A unidade monetária depende do campo e da modalidade. Pix e boleto usam amount em reais, com até duas casas decimais. Cobranças e chargebacks de cartão usam value em centavos inteiros: 5000 representa R$ 50,00. Em instruções de split, split[].value segue o tipo da alocação, conforme o guia de split; não converta todos os campos de cartão indistintamente. Preserve a precisão de centavos na aplicação. Datas de vencimento usam YYYY-MM-DD; campos de horário e filtros usam UTC conforme a página correspondente.
Datas, documentos e identificadores nos exemplos são demonstrativos. Atualize as datas de vencimento antes de executar uma criação e substitua IDs pelos retornados na sua conta. O CPF fictício tem formato verificável, mas não representa autorização para usar dados de terceiros.
Leia a regra de repetição de cada endpoint. A presença de customer_code, metadata ou de um header arbitrário não estabelece deduplicação de uma criação. Veja as regras da operação antes de habilitar repetição.
Repetição nas operações de cartão
As operações de escrita de cartão documentam Idempotency-Key. A chave é opcional, mas recomendada. Preserve método, caminho e os bytes do corpo em uma repetição da mesma operação. Uma nova tentativa em /retry é outra operação financeira e não deve ser usada para resolver um timeout. Consulte a criação de cobrança de cartão para as regras específicas.
Guias relacionados
Primeiros passos · Erros e recuperação · Idempotência e repetição · Recebendo webhooks
Escolha o próximo passo
Primeiros passos em Sandbox apresenta um fluxo completo de teste. Use Erros e recuperação para falhas, Idempotência e repetição para cartão e Recebendo webhooks para notificações.
Para agentes de IA
Localize páginas pelo índice https://docs.pagou.com.br/llms.txt e leia seus conteúdos completos em Markdown, acrescentando .md à URL pública. Os exemplos por linguagem estão em tabs; cada alternativa implementa a operação descrita na mesma página. Leia pré-requisitos, unidades, estados e recuperação antes de executar uma escrita financeira. Não inferir um campo ou uma operação ausente do contrato.
Last updated