Visão Geral
Cobranças Pix imediatas (QR Code dinâmico), devoluções e webhook de notificação
A API de Pagamentos gera cobranças Pix imediatas com QR Code dinâmico, permite consultar, listar e cancelar as cobranças emitidas, solicitar devoluções de Pix recebidos e cadastrar a URL de webhook que recebe as notificações de pagamento e devolução.
Endpoints
| Operação | Método e rota |
|---|---|
| Criar cobrança imediata | POST /api/v1/pix-charges |
| Consultar cobrança | GET /api/v1/pix-charges/{txid} |
| Listar cobranças | GET /api/v1/pix-charges |
| Cancelar cobrança | PUT /api/v1/pix-charges/{txid}/cancel |
| Solicitar devolução | POST /api/v1/pix-refunds |
| Consultar devolução | GET /api/v1/pix-refunds/{pixRefundId} |
| Listar devoluções | GET /api/v1/pix-refunds |
| Cadastrar webhook | POST /api/v1/webhooks |
| Atualizar webhook | PUT /api/v1/webhooks/{id} |
| Listar webhooks | GET /api/v1/webhooks |
Todos os endpoints exigem autenticação mTLS. Veja Autenticação. As cobranças, devoluções e webhooks ficam vinculados ao cliente identificado pela credencial — não é possível consultar recursos de outro cliente.
Fluxo da cobrança
Status da cobrança
O campo status é sempre devolvido como texto simples (string), tanto na criação
quanto na consulta e na listagem.
| Status | Significado |
|---|---|
CREATED | Registrada, ainda não disponibilizada para pagamento |
ACTIVE | Cobrança gerada, ainda não paga nem expirada |
PAID | Cobrança paga; ainda aceita devolução dentro da janela de 90 dias |
PARTIALLY REFUNDED | Pix recebido devolvido parcialmente |
REFUNDED | Pix recebido devolvido integralmente |
EXPIRED | Prazo de expiração atingido; cobrança não é mais válida |
Cancelada | Cancelada via PUT /pix-charges/{txid}/cancel |
Repare que Cancelada é o único valor em português — é um rótulo herdado do sistema
legado e não foi normalizado. Compare a string exatamente como documentado aqui, não
pelo padrão dos demais valores.
Status da devolução
| Status | Código | Significado |
|---|---|---|
CREATED | 1 | Devolução registrada |
PROCESSING | 2 | Devolução enviada e em processamento |
RETURNED | 3 | Devolução liquidada |
NOT FINISHED | 4 | Devolução não concluída — ver statusReason |
ERROR | 99 | Falha ao processar a devolução |
Cabeçalhos comuns
| Header | Obrigatório | Descrição |
|---|---|---|
Content-Type | sim (com body) | application/json |
x-transaction-id | não | UUID de rastreio da requisição (ex.: 328d5e1a-06dd-4263-8081-0a2ec31c1f9a). Se ausente, é gerado pela API e devolvido em todo corpo de erro (xTransactionId) |
Envie sempre um x-transaction-id próprio e registre-o no seu log. Em caso de erro,
informe esse valor ao suporte para localizar a requisição — ele também vem no corpo do
erro, mesmo quando você não o envia.
Paginação
As listagens retornam uma página no formato abaixo e aceitam os query params page
(começa em 0), size (padrão 20) e sort (campo,asc ou campo,desc).
{
"content": [],
"number": 0,
"size": 20,
"totalElements": 0,
"totalPages": 0,
"numberOfElements": 0,
"first": true,
"last": true,
"empty": true
}| Campo | Descrição |
|---|---|
content | Itens da página |
number | Número da página retornada (começa em 0) |
size | Tamanho da página solicitado |
totalElements | Total de itens que atendem aos filtros |
totalPages | Total de páginas disponíveis |
numberOfElements | Quantidade de itens nesta página |
first / last | Indica se é a primeira / última página |
Corpo de erro
Qualquer erro (mapeado ou não) devolve o mesmo formato:
{
"timestamp": "2026-09-15T14:30:00-03:00",
"errorCode": "VALIDACAO_INVALIDA",
"httpStatus": 400,
"mensagem": "Descrição do erro",
"xTransactionId": "328d5e1a-06dd-4263-8081-0a2ec31c1f9a",
"details": []
}details só vem preenchido em erro de validação de campo, com { "campo": "...", "erro": "..." } por campo inválido.