Pagamentos, assinaturas e subtenants
com a API Calebe Pay.

Acompanhe até a confirmação

GET /v1/transactions/{id} retorna o estado guardado. POST /v1/transactions/{id}/refresh consulta o provedor de pagamento e atualiza o registro. Use os webhooks como aviso e mantenha um polling limitado no seu backend, retomando pedidos pendentes depois de reinícios.

Veja todos os códigos HTTP e as regras de retentativa em Respostas, validação e estados.

Assinaturas e Pix Automático

Cadastre a recorrência uma vez e a Calebe Pay emite a cobrança de cada ciclo: um boleto, um link de Pix ou um débito por Pix Automático, na antecedência que você escolher. O calendário é em meses (12 = anual), no horário de Brasília, e cada cobrança emitida segue as mesmas tarifas, o mesmo split e os mesmos webhooks de uma cobrança avulsa.

No Pix Automático, o pagador aprova uma vez no aplicativo do banco e os débitos seguintes acontecem sem nova ação dele. O primeiro vencimento precisa estar ao menos 2 dias à frente, porque cada débito é agendado de 2 a 10 dias antes.

Emita seu primeiro boleto

Com o boleto habilitado para a sua conta, emita uma chave com boleto:write e transactions:read. Endereço do pagador e vencimento YYYY-MM-DD são obrigatórios.

O guia inclui preparação do payload com vencimento válido, exemplos cURL/Node/Python/Go, limites e diagnósticos. No modo de teste, URL e linha digitável são nulas. O boleto real sai, sempre que possível, com um Pix do mesmo valor, válido até o fim do dia do vencimento, e boleto_url é o PDF gerado pela Calebe Pay, com o QR desse Pix. processing de boleto ainda não confirma pagamento.

Cadastre um subtenant e tente a conversão automática

Use uma chave de produção com subtenants:write. O tenant autenticado será sempre o pai do novo cadastro. O exemplo omite provider_id, então a API seleciona o primeiro provider marketplace ativo no roteamento e aplica suas taxas padrão aos meios de pagamento que não vierem em MerchantSplit. Os valores abaixo são fictícios: substitua todo o cadastro por dados reais e revisados antes de enviar.

curl --fail-with-body -X POST "$CALEBE_API_URL/v1/subtenants" \
  -H "X-API-Key: $CALEBE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cadastro-loja-exemplo-1" \
  --data '{
    "tenant": { "name": "Loja Exemplo", "slug": "loja-exemplo" },
    "registration": {
      "Name": "Loja Exemplo LTDA",
      "CommercialName": "Loja Exemplo",
      "Identity": "11222333000181",
      "Email": "financeiro@loja-exemplo.com.br",
      "ResponsibleName": "Maria da Silva",
      "ResponsibleIdentity": "52998224725",
      "ResponsibleBirthDate": "1990-01-01",
      "ResponsiblePhone": "11999999999",
      "Address": {
        "ZipCode": "01310100", "Street": "Avenida Paulista",
        "Number": "1000", "District": "Bela Vista",
        "CityName": "São Paulo", "StateInitials": "SP", "CountryName": "Brasil"
      }
    }
  }'

A resposta inclui tenant_id, subaccount_id e conversion_status. Somente converted confirma a subconta; creating ou unknown exigem acompanhamento sem começar outro cadastro, e failed contém um diagnóstico seguro. HTTP 202 significa processamento ou resultado externo incerto. Em timeout, repita o mesmo corpo com a mesma chave.

Liste subtenants e emita suas chaves

Lista filhos diretos do tenant autenticado. Use include_descendants=true para todos os níveis, status=active ou suspended para filtrar e limit/offset para paginar. O padrão é 50 itens, com máximo de 100. Retorna data e meta; meta.count é a quantidade da página. Teste e produção consultam o mesmo cadastro, sem acesso ao próprio tenant, pais, irmãos ou outras árvores.

curl --fail-with-body \
  "$CALEBE_API_URL/v1/subtenants?include_descendants=true&status=active&limit=50&offset=0" \
  -H "X-API-Key: $CALEBE_API_KEY"

A chave do pai precisa conter subtenants:keys:write e cada permissão que será delegada. Selecione esses scopes em Chaves de API; chaves existentes não os recebem automaticamente. O destino deve ser um descendente ativo, com ancestrais ativos. Nome e scopes são obrigatórios. O modo omitido herda o da chave autenticada: teste só emite teste; produção pode emitir teste ou produção.

curl --fail-with-body -X POST \
  "$CALEBE_API_URL/v1/subtenants/$SUBTENANT_ID/api-keys" \
  -H "X-API-Key: $CALEBE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chave-erp-loja-1" \
  --data '{"name":"ERP da loja","mode":"test","scopes":["pix:write","transactions:read"]}'

O HTTP 201 retorna data.key, secret_available: true e os metadados em api_key. Guarde o segredo no backend: ele aparece uma única vez. A mesma tentativa retorna 200, Idempotency-Replayed: true, key: null e secret_available: false, sem emitir outra credencial. Dados diferentes geram 409 idempotency_conflict. Se perder o segredo, identifique a chave pelo replay, revogue no portal e faça outra emissão deliberada com nova idempotência.

Scopes não presentes no pai geram 403 scope_not_delegable; elevar teste para produção gera 403 key_mode_not_allowed. Destino fora da árvore ou o próprio tenant recebe 404. Emitir uma chave não habilita pagamentos nem altera roteamento. Revogar a chave do pai não revoga automaticamente as chaves dos filhos.

Autenticação e hierarquia

Use X-API-Key nos endpoints públicos. A chave define o tenant e o modo (teste ou produção) de tudo o que ela cria; no cadastro de subtenant, ela define o pai. A sessão Bearer do painel é independente.

Todos os escopos, as 30 operações da API e o que só existe no painel estão em Tudo o que dá para fazer pela API.

Um contrato pequeno e explícito

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.

Veja a lista completa, com assinaturas, Pix Automático, centros de custo e subtenants, em Tudo o que dá para fazer pela API, e todos os schemas e códigos de erro no OpenAPI. Pix, boleto e cartão usam a divisão automática das tarifas configuradas pela Calebe Pay; não envie recebedores no corpo. Não há endpoints de saque, cancelamento ou estorno de cobranças.

Repita com segurança

Uma chave idempotente identifica uma tentativa comercial: pagamento, checkout, assinatura, autorização ou cadastro de subtenant. A mesma chave e o mesmo payload reutilizam o recurso. A mesma chave com dados diferentes resulta em conflito.

1. Persista a chave e o payload antes da chamada.
2. Faça a chamada e salve os IDs retornados.
3. Se houver timeout, reutilize a chave original. Não gere outra automaticamente.
4. Se o resultado for unknown, reconcilie antes de iniciar uma nova tentativa.

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

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.

Prompt de integração

Leia llms.txt, api.md, integration.md e openapi.json da Calebe Pay.
Implemente Pix e boleto no backend do meu sistema. Leia também boleto.md.
Solicite uma chave com 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 com uma chave de teste (cp_test_) e simule o pagamento em /v1/transactions/{id}/simulate.
Receba transaction.updated pelo webhook assinado e trate paid como definitivo.
Para cobranças recorrentes, leia subscriptions.md e use /v1/subscriptions; no Pix Automático, peça a autorização antes.
Para cadastrar empresas filhas, use POST /v1/subtenants com chave de produção e subtenants:write.
Não envie parent_id; leia conversion_status e preserve a mesma Idempotency-Key em resultado incerto.
Não invente endpoints ou meios de pagamento não implementados.

Escolha como integrar os pagamentos da sua operação

Antes de implementar, conheça os fluxos e recursos disponíveis: integração Pix com QR Code e copia e cola, integração de boleto com vencimento e dados do pagador e link de pagamento com Pix e boleto. A visão geral do gateway de pagamento Calebe Pay ajuda a escolher entre o portal e a API para o seu negócio.