Idempotência por tentativa
Repetir chave e corpo recupera a tentativa registrada. Alterar o corpo com a mesma chave retorna conflito 409.
API DE PAGAMENTO PARA DESENVOLVEDORES
API de pagamento Pix e boleto para integrar ao seu produto.
Crie cobranças, gere links de pagamento e consulte transações com uma API REST em JSON. O Calebe Pay reúne autenticação por chave, contrato OpenAPI 3.1, webhooks assinados e teste simulado para a integração do seu backend.
- REST + JSON
- contrato HTTP para seu backend
- OpenAPI 3.1
- schemas e respostas documentados
- Webhooks
- assinatura HMAC-SHA256
- Modo de teste
- sem envio ao provedor
PASSO A PASSO
Da primeira chamada à operação em produção
A integração inclui criação, acompanhamento e recuperação de falhas. Planeje os três antes de liberar pedidos reais.
- 01
Gere a chave com os escopos necessários
Use pix:write ou boleto:write para emitir e transactions:read para consultar. A chave define a conta de criação e fica apenas no backend.
- 02
Persista antes de enviar
Salve referência, corpo e Idempotency-Key no seu pedido. Depois da criação, associe o ID da transação ao registro local.
- 03
Teste estados e eventos
Simule pagamento e expiração, valide a assinatura do webhook e trate eventos repetidos. Confira os caminhos de erro e de resultado incerto.
- 04
Ative o fluxo real
Confirme a liberação de produção e os métodos habilitados. Configure a chave e os webhooks de produção e valide o ambiente de cada resposta.
EXEMPLO REAL DA API
Como validar um webhook de pagamento
A assinatura Calebe-Signature usa os bytes crus do corpo. Verifique-a antes de interpretar o JSON e atualizar o pedido.
- Guarde o segredo de assinatura no servidor, separado do código público.
- Persista o id do evento para tratar repetições. A ordem de entrega não é garantida.
- A assinatura valida a origem do evento; confirme também estado, valor, pedido e ambiente antes da liberação.
import { createHmac, timingSafeEqual } from 'node:crypto';
// Confere a assinatura Calebe-Signature (t=...,v1=...) sobre os bytes crus do corpo.
export function assinaturaValida(corpo, cabecalho, segredo, tolerancia = 300) {
if (typeof cabecalho !== 'string' || !Buffer.isBuffer(corpo)) return false;
const partes = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(cabecalho);
if (!partes) return false;
const [, timestamp, assinatura] = partes;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > tolerancia) return false;
const esperado = createHmac('sha256', segredo)
.update(`${timestamp}.`).update(corpo).digest();
return timingSafeEqual(esperado, Buffer.from(assinatura, 'hex'));
}
// Evento recebido: { "type": "transaction.updated", "previous_status": "pending",
// "data": { "transaction_id": "txn_...", "status": "paid", "livemode": true } }RECURSOS
Recursos para integrar e operar pagamentos
O contrato documenta tanto o caminho de sucesso quanto o comportamento quando a emissão ou a consulta falha.
Diagnóstico de requisições
Use códigos de erro e request_id para investigar o que aconteceu, sem registrar credenciais ou dados completos do pagador.
Webhooks com retentativas
Eventos assinados têm entrega com retentativas e acompanhamento pelo portal. Seu receptor deve persistir e deduplicar os eventos.
Contrato e exemplos
OpenAPI 3.1, guia de operação e exemplos em Node.js, Python e Go ajudam a implementar a chamada e tratar a resposta.
Chaves com permissões
Escopos limitam emissão e leitura. Chaves de teste e produção acessam as transações de seus respectivos modos.
Monitor de integração
Acompanhe chamadas e resultados no portal conforme o perfil de acesso, junto das transações da conta.
Principais endpoints da API de pagamentos
Use os endpoints de emissão para criar a tentativa e os de leitura para acompanhar o mesmo registro. Todos seguem o contrato público da Calebe Pay.
- POST /v1/pix: cria cobrança Pix com validade configurável.
- POST /v1/boleto: solicita emissão de boleto com vencimento e dados do pagador.
- POST /v1/checkouts: cria um link que oferece os meios de pagamento escolhidos.
- GET /v1/transactions e GET /v1/transactions/{id}: listam e consultam o estado persistido.
- POST /v1/transactions/{id}/refresh: consulta o provedor e atualiza a transação existente.
- POST /v1/transactions/{id}/simulate: simula pagamento ou expiração de cobrança de teste pendente.
Abrir a referência OpenAPI da Calebe Pay →Ver a documentação interativa da API →
API de pagamento para ERP, SaaS e e-commerce
O backend do seu sistema traduz uma venda ou fatura em uma requisição de cobrança. A referência comercial relaciona os dois registros; o ID retornado permite consultar a transação e reconciliar mudanças recebidas por webhook.
Uma software house pode operar com contas vinculadas para os estabelecimentos atendidos, conforme a estrutura configurada. Cada conta usa suas próprias credenciais de emissão. A divisão de tarifas é derivada pelo servidor e não deve ser enviada como recebedores livres no pedido.
Integração Pix com QR Code →Emissão de boleto por API →Split para contas vinculadas →
Como tratar falhas sem duplicar a cobrança
Uma falha de rede não informa se o pedido chegou ao servidor. Preserve a chave de idempotência e o payload original; use o ID conhecido ou repita a mesma tentativa para recuperar o registro. Um status unknown exige reconciliação, não uma cobrança com chave nova.
HTTP 200 ou 201 não é confirmação de pagamento. O sistema deve interpretar o status da transação e distinguir teste de produção. Webhook e consulta de status se complementam, inclusive depois de reinícios da aplicação.
Documentação para desenvolvedores e assistentes de código
Use o OpenAPI para conferir campos, tipos e respostas antes de escrever o cliente. Os exemplos executáveis demonstram as chamadas sem repetição automática; o guia explica autenticação, ambiente, webhook e resultado incerto.
O arquivo llms.txt aponta para o contrato e os guias que um assistente de programação deve ler. Isso ajuda a manter a implementação alinhada aos endpoints disponíveis, sem inventar operações de cancelamento, saque ou estorno.
Exemplos de integração em Node.js, Python e Go →Contexto técnico para assistentes de programação →
PERGUNTAS FREQUENTES
Dúvidas sobre API de pagamento
Não achou a resposta? Fale com um especialista pelo WhatsApp.
O que é uma API de pagamento?
É uma interface para o sistema criar cobranças, consultar o estado e receber eventos de pagamento. A API do Calebe Pay oferece esses recursos para Pix, boleto e links de pagamento com HTTP e JSON.
Como autenticar na API do Calebe Pay?
Envie a chave no cabeçalho X-API-Key a partir do seu backend. Ela é criada no portal com os escopos da integração. Não exponha o segredo no navegador, no aplicativo do cliente nem em repositórios.
A API de pagamento tem sandbox?
Há um modo de teste simulado com chave cp_test_, sem envio ao provedor. O sandbox remoto está disponível para boleto quando configurado; Pix remoto funciona somente em produção. Cobranças reais dependem da liberação da conta.
Posso integrar com PHP, Node.js, Python ou Java?
Sim. Qualquer linguagem com suporte a HTTPS e JSON pode usar a API. A documentação inclui contrato OpenAPI e exemplos executáveis em Node.js, Python e Go, além do exemplo em cURL.
Como evitar cobranças duplicadas em uma falha de rede?
Salve Idempotency-Key e corpo antes da primeira chamada e preserve ambos ao repetir. A API recupera a tentativa registrada. Se o resultado estiver incerto, consulte e reconcilie essa transação antes de considerar uma nova emissão.
Posso criar a cobrança diretamente pelo navegador?
A chamada autenticada deve partir do seu backend, que protege a chave de API. O frontend pode apresentar os dados de pagamento retornados ou abrir um link de checkout criado pelo servidor.
CADASTRO 100% ONLINE · CERCA DE 6 MINUTOS