Documentação API pública↓ Baixar OpenAPI
FEITO PARA INTEGRAR

Seu próximo pagamento
começa com uma chamada.

Crie cobranças Pix e boleto, acompanhe transações e conecte a sua operação à Calebe Pay. Um contrato simples, com isolamento por tenant.

Criar meu primeiro Pix →Guia completo ↗
Escolha o ambiente de cada método.O simulador local atende Pix e boleto com simulated: true, sem artefatos pagáveis. Safe2Pay oferece sandbox para boleto, com credencial própria e environment: sandbox. Pix Safe2Pay exige produção e autorização explícita. Ver documentação oficial ↗
{ }Contrato legível por máquinas

OpenAPI 3.1, tipos, autenticação, erros e exemplos de respostas.

⌘Exemplos que você pode executar

Node.js, Python e Go. Sem bibliotecas externas, sem retries ocultos.

✳Pronto para seu agente de IA

Instruções diretas para construir uma integração sem inventar endpoints.

01. Crie seu primeiro Pix

Emita uma chave para o tenant no painel. Mantenha o segredo no seu servidor e salve uma chave de idempotência no pedido antes da primeira chamada. O exemplo usa o simulador e dados fictícios.

TERMINAL · cURL
curl --fail-with-body http://localhost:18080/v1/pix \
  -H "X-API-Key: $CALEBE_API_KEY" \
  -H "Idempotency-Key: pedido-2026-00042-pix-1" \
  -H "Content-Type: application/json" \
  --data '{
    "amount": 1250,
    "reference": "pedido-2026-00042",
    "description": "Pedido de demonstração",
    "customer": {
      "name": "Cliente de demonstração",
      "document": "00000000000",
      "email": "cliente@example.com",
      "phone": "11999999999",
      "address": {
        "zip_code": "01001000",
        "street": "Rua Exemplo",
        "number": "100",
        "district": "Centro",
        "city": "São Paulo",
        "state": "SP"
      }
    },
    "expires_in": 3600
  }'

amount: 1250 corresponde a R$ 12,50. Salve data.id para consultar o pagamento. A resposta traz status, simulated, pix_copy_paste, pix_qr_code e expires_at.

Origem da API neste ambiente: http://localhost:18080. Os exemplos usam a origem publicada no contrato OpenAPI. Configure essa origem e sua chave nas variáveis de ambiente do backend integrador. No desenvolvimento local, a API direta usa http://localhost:18080; o portal encaminha chamadas pelo prefixo /api.

Emita seu primeiro boleto

Habilite boleto em enabled_methods do provider, configure uma regra desse método e emita uma chave com boleto:write e transactions:read. Endereço do pagador e vencimento YYYY-MM-DD são obrigatórios.

POST/v1/boletoEndereço + boleto.due_date · mesma idempotência do Pix

O guia inclui preparação do payload com vencimento válido, exemplos cURL/Node/Python/Go, limites e diagnósticos. No simulador, URL e linha digitável são nulas. processing de boleto ainda não confirma pagamento.

Guia completo de boletos →

Subcontas por tenant

O super admin pode criar, importar, consultar e atualizar subcontas Safe2Pay. Um provider marketplace exige vínculo ativo do tenant exato: clientes de uma software house não compartilham sua subconta automaticamente.

A gestão usa sessão administrativa e chave de produção da matriz Safe2Pay, mesmo com cobranças em sandbox. Tokens ficam cifrados e nunca são retornados. Cadastro remoto não é simulação, mesmo quando o provider usa sandbox para cobranças. Respostas incertas exigem reconciliação; não geram nova criação automática.

Guia administrativo de subcontas →

Controle de pagamentos em produção

Em Providers, o super admin consulta e salva o controle global de produção. A alteração é auditada e aplicada sem reiniciar a API; chaves de tenant não têm acesso.

Ligar o controle não amplia o escopo autorizado no servidor. O painel mostra separadamente o valor salvo e se existe autorização para emitir. Em falha de leitura da configuração, as emissões em produção ficam bloqueadas.

Contrato e operação →

02. Autenticação e hierarquia

Use X-API-Key nos endpoints públicos. A chave define o tenant da cobrança. Para cobrar em nome de um cliente filho, utilize uma chave desse filho. A sessão Bearer do painel é independente.

O que você precisaComo fazer
Criar PixChave com escopo pix:write
Criar boletoChave com escopo explícito boleto:write
Ler transaçõesChave com escopo transactions:read
Atualizar pelo provedortransactions:read + pix:write ou boleto:write, conforme o método
Ver transações dos filhosinclude_descendants=true na listagem
Selecionar um filho na leituratenant_id dentro do escopo permitido
Não envie tenant_id no corpo de POST /v1/pix ou POST /v1/boleto. Nunca coloque chaves de API no React, Expo ou Electron renderer. Clientes públicos chamam o seu backend.

03. Um contrato pequeno e explícito

POST/v1/pixCriar cobrança · exige Idempotency-Key
GET/v1/transactionsListar · limit, offset, status, method, reference, tenant_id
GET/v1/transactions/{id}Ler estado persistido
POST/v1/transactions/{id}/refreshConsultar estado no provedor

Um objeto retorna {data: objeto}. Uma lista retorna {data: [], meta: {limit, offset, count}}. Um erro da aplicação retorna {error: {code, message, request_id}}. O limite padrão é 50 itens, com máximo de 100 por página.

Consulte os schemas, os endpoints do painel e a autenticação em OpenAPI. Esta versão emite Pix e boleto; ainda não cria cartão, split dinâmico, saques, cancelamentos ou estornos.

04. Repita com segurança

Uma chave idempotente identifica uma tentativa comercial de pagamento. A mesma chave e o mesmo payload reutilizam a transação. A mesma chave com dados diferentes resulta em conflito.

  1. Persista a chave e o payload junto ao seu pedido.
  2. Faça a chamada e salve o ID retornado.
  3. Se houver timeout, reutilize a chave original. Não gere outra automaticamente.
  4. Se o status for unknown, reconcilie antes de tentar uma nova cobrança.

O SDK TypeScript não realiza retries automáticos. Veja a tabela de erros e retentativas.

05. Acompanhe até a confirmação

GET retorna o estado local. POST …/refresh consulta o conector e atualiza o registro. O simulador permite mudar o estado pelo painel; isso não move dinheiro.

EstadoComportamento da integração
processing / pendingContinue consultando de forma limitada.
paidPagamento confirmado. Valide pelo backend antes de entregar.
expired / failedNão libere o pedido. Mostre uma orientação clara.
unknownResultado incerto. Reconcilie; não crie cobrança duplicada.
refundedDevolução informada pelo provedor; atualize seu pedido.
Ainda não há envio de webhooks para tenants. Faça polling no seu backend e retome pedidos pendentes depois de reinícios.

06. Construa com seu agente de IA

Forneça os dois arquivos abaixo ao seu assistente de programação. O guia contém a sequência correta, os limites da primeira versão e critérios objetivos de teste.

Abrir llms.txt ↗Abrir OpenAPI ↗

Prompt de integração

CONTEXTO PARA SEU AGENTE
Leia llms.txt, integration.md e openapi.json da Calebe Pay.
Implemente Pix e boleto no backend do meu sistema. Leia também boleto.md.
Habilite boleto no provider e solicite boleto:write explicitamente.
Use variáveis de ambiente para a chave e a origem da API.
Persista pedido, payload e chave idempotente antes da rede.
Consulte pelo backend e libere apenas quando paid em produção.
Persista o vencimento do boleto; não recalcule a data em retries.
Trate timeout como resposta incerta, sem gerar nova chave.
Teste no simulador e identifique simulated=true na interface.
Não invente webhooks ou meios de pagamento não implementados.