Características do Ambiente Sandbox

Ambiente Sandbox

Características do Ambiente de Produção

Ambiente de Produção

Fluxo de Desenvolvimento Recomendado

Recomendações

Nossos Ambientes

Super Pagamentos

Bem-vindo a nossa documentação. Aqui você poderá aprender mais sobre o funcionamento das nossas API's, realizar testes e mais.

Introdução

Guia de Suporte

Autenticação das APIs

Guia de Erros

Bem-vindo à documentação da API da Super Pagamentos!  
Nossa API foi desenvolvida para oferecer uma integração robusta, segura e intuitiva com a nossa plataforma de intermediação de pagamentos. Através dela, é possível criar e gerenciar subcontas, processar transações, tokenizar cartões, configurar planos de assinatura, antecipar recebiveis e muito mais.  

A rota `/auth` gera tokens JWT com duração de 3600 segundos. Com esses tokens é possível autenticar as demais rotas da aplicação para.

 Recomenda-se **nunca armazenar as chaves em ambientes front-end**, sempre utilizar em **ambientes protegidos por um certificado SSL** e **NUNCA compartilhar suas credenciais** com outras pessoas (nem mesmo do Suporte da Super).

Autenticar conta

Cria uma nova subconta do tipo Pessoa Física. Com esta subconta, você poderá gerenciar contas bancárias, clientes, planos, assinaturas e realizar split de pagamentos de forma independente.

Adicionar subconta PF

Cria uma nova subconta do tipo Pessoa Jurídica. Com esta subconta, você poderá gerenciar contas bancárias, clientes, planos, assinaturas e realizar split de pagamentos de forma independente.

Adicionar subconta PJ

Lista todas as subcontas cadastradas para a empresa. A resposta inclui informações detalhadas de cada subconta, como dados do responsável legal, dados jurídicos (para PJ), endereços e status da conta. Os resultados são paginados para melhor performance.

Listar subcontas

Busca os dados de uma subconta específica que pertence à empresa cadastrada. A resposta inclui informações detalhadas da subconta, como dados do responsável legal, dados jurídicos (para PJ), endereços e status da conta.

Detalhar subconta

Remove uma subconta específica. Esta operação é irreversível e deve ser utilizada com cautela.

Remover subconta

Crie uma nova conta bancária para a empresa.

A criação de uma conta bancária é **essencial para realizar saques** dos valores recebidos através da Super Pagamentos. 

**Importante:** A conta bancária deve obrigatoriamente pertencer ao mesmo titular/CNPJ da conta na Super Pagamentos. Contas bancárias de terceiros não são aceitas por questões de segurança e conformidade.

**Tipos de conta aceitos:**
- Conta Corrente
- Conta Poupança

**Documentação necessária:**
- A conta bancária deve estar no mesmo nome/CNPJ cadastrado na Super Pagamentos
- Todos os dados bancários devem estar corretos e atualizados

**Operação em subconta:**
Para criar uma conta bancária em uma subconta específica, inclua o header `x-subaccount-id` com o ID da subconta. Quando este header é fornecido, a operação será realizada no contexto da subconta especificada, em vez da conta principal autenticada.

Adicionar conta bancária

Lista todas as contas bancárias cadastradas para a empresa. A resposta inclui informações detalhadas de cada conta, como dados do titular, dados bancários e status da conta. Os resultados são paginados para melhor performance.

**Operação em subconta:**
Para listar as contas bancárias de uma subconta específica, inclua o header `x-subaccount-id` com o ID da subconta. Quando este header é fornecido, a operação será realizada no contexto da subconta especificada, em vez da conta principal autenticada.

Listar contas bancárias

Busca os dados de uma conta bancária específica que pertence à empresa cadastrada. A resposta inclui informações detalhadas da conta, como dados do titular, dados bancários e status da conta.

**Operação em subconta:**
Para buscar uma conta bancária específica de uma subconta, inclua o header `x-subaccount-id` com o ID da subconta. Quando este header é fornecido, a operação será realizada no contexto da subconta especificada, em vez da conta principal autenticada.

Detalhar conta bancária

Remove uma conta bancária específica que pertence à empresa cadastrada. Esta operação é irreversível e deve ser utilizada com cautela.

**Operação em subconta:**
Para deletar uma conta bancária específica de uma subconta, inclua o header `x-subaccount-id` com o ID da subconta. Quando este header é fornecido, a operação será realizada no contexto da subconta especificada, em vez da conta principal autenticada.

Remover conta bancária

Cria um novo cliente no sistema. Nenhum campo é obrigatório, exceto os campos do endereço quando informado.

Adicionar cliente

Lista todos os clientes cadastrados. A resposta inclui informações detalhadas de cada cliente, como dados pessoais, contato e endereço. Os resultados são paginados para melhor performance.

Listar clientes

Busca os dados de um cliente específico. A resposta inclui informações detalhadas do cliente, como dados pessoais, contato e endereço.

Detalhar cliente

Atualiza os dados de um cliente específico. Nenhum campo é obrigatório, exceto quando o cliente não possui um endereço cadastrado e deseja cadastrar um novo endereço - neste caso, todos os campos do endereço são obrigatórios.

Atualizar cliente

Remove um cliente específico do sistema. Esta operação é irreversível e deve ser utilizada com cautela.

Remover cliente

Tokeniza um cartão de crédito e o associa a um cliente específico. A tokenização é um processo de segurança que substitui os dados sensíveis do cartão por um token único e seguro. Este token pode ser utilizado para realizar compras futuras sem a necessidade de informar novamente os dados do cartão.

**Importante:**
- Os dados do cartão são criptografados e armazenados de forma segura
- O token gerado é único e específico para cada cartão
- O token pode ser utilizado apenas para o cliente ao qual foi associado
- A tokenização reduz riscos de segurança ao não expor os dados reais do cartão

Tokenizar cartão de crédito

Busca os dados de um cartão tokenizado específico. Esta rota retorna informações parciais do cartão (apenas os primeiros e últimos 4 dígitos) por questões de segurança, mantendo os dados sensíveis protegidos.

**Importante:**
- Apenas os primeiros e últimos 4 dígitos do cartão são retornados
- Os dados completos do cartão nunca são expostos na API
- O cartão só pode ser consultado se pertencer ao cliente associado

Recuperar dados do cartão tokenizado

Remove um cartão tokenizado específico. Esta operação é irreversível e deve ser utilizada com cautela. Após a remoção, o token não poderá mais ser utilizado para realizar transações.

**Importante:**
- A operação é irreversível
- O cartão só pode ser removido se pertencer ao cliente associado
- Após a remoção, o token não poderá mais ser utilizado

Remover token

Cria uma nova transação no método de pagamento selecionado. Essa rota pode ser utilizada para criar transações com cartão de crédito, cartão tokenizado, PIX e boleto. Também é possível realizar splits entre subcontas.

**Tipos de pagamento disponíveis:**
- Cartão de Crédito: Pagamento direto com cartão de crédito, requerendo dados completos do cliente, endereço e cartão
- Cartão Tokenizado: Pagamento com cartão de crédito previamente tokenizado
- PIX: Pagamento instantâneo via PIX
- Boleto: Geração de boleto bancário

Gerar transação

Lista todas as transações realizadas pela empresa autenticada. Esta rota suporta paginação e filtros para facilitar a busca de transações específicas.

Listar transações

Retorna os detalhes de uma transação específica pelo ID.

Detalhar transação

Realiza o estorno de uma transação. É importante notar que:

- Apenas transações realizadas com cartão de crédito podem ser estornadas
- É necessário possuir saldo disponível para realizar o estorno
- O estorno não é possível se a transação já foi recebida em D+30, antecipada ou se alguma parcela foi paga (em caso de parcelamentos) e não possuir saldo disponível na conta!

Estornar transação

Cria uma nova assinatura recorrente para um cliente. As assinaturas recorrentes permitem cobrar automaticamente um valor fixo em intervalos regulares, facilitando a gestão de pagamentos recorrentes.

**Fluxo de funcionamento:**
1. A assinatura é criada com os dados do cliente, cartão, valores e frequência
2. No dia especificado em `dueDate`, é realizada a primeira cobrança
3. As cobranças subsequentes ocorrem automaticamente de acordo com a `frequency` definida
4. O sistema respeita o `tolerancePeriod` para tentativas de cobrança em caso de falha
5. A assinatura pode ter duração limitada (`duration`) ou ser vitalícia
6. É possível definir uma data de expiração (`expirationDate`) para encerramento automático

**Vantagens:**
- Automatização de cobranças recorrentes
- Gestão simplificada de assinaturas
- Suporte a diferentes frequências de cobrança
- Possibilidade de split entre subcontas
- Período de tolerância para tentativas de cobrança
- Flexibilidade na duração e expiração

**Validações importantes:**
- O cliente e o cartão devem existir e estar ativos
- A data de início (`dueDate`) não pode ser no passado
- O valor total dos splits deve somar 100% ou o valor total da assinatura
- Apenas uma subconta pode ser responsável por chargebacks
- O período de tolerância é opcional e deve ser maior que 0
- O valor de setup é opcional e deve ser maior que 100 (R$ 1,00) quando informado

Adicionar assinatura

Lista todas as assinaturas da companhia. A resposta inclui informações detalhadas de cada assinatura, como dados do plano, splits e status. Os resultados são paginados para melhor performance.

Listar assinaturas

Recupera os dados detalhados de uma assinatura específica. A resposta inclui informações como dados do cliente, valores, frequência, splits e status da assinatura.

Detalhar assinatura

Atualiza os dados de uma assinatura existente. Esta rota permite atualizar diversos campos da assinatura, exceto os dados de split. Para alterar os dados de split, é necessário utilizar a rota específica para isso.

Atualizar assinatura

Adiciona um novo split para uma assinatura existente. O split pode ser configurado por valor fixo (amount) ou porcentagem (percentage) do valor da assinatura. É possível definir se a subconta será responsável pelos chargebacks da assinatura através do campo chargebackLiable.

**Importante:**
- Para splits do tipo 'amount', o campo splitAmount é obrigatório
- Para splits do tipo 'percentage', o campo splitPercentage é obrigatório
- O valor total dos splits não pode ultrapassar o valor disponível após a taxa da assinatura
- A subconta deve estar aprovada para realizar a operação

Adicionar split na assinatura

Remove um split específico de uma assinatura. Esta operação é irreversível e deve ser utilizada com cautela. Após a remoção do split, o valor total da assinatura será ajustado automaticamente.

Remover split da assinatura

Suspende uma assinatura existente, interrompendo temporariamente as cobranças recorrentes. Esta operação é útil quando o cliente precisa de uma pausa temporária no serviço, mas deseja manter a assinatura para reativação futura.

**Impacto da suspensão:**
- As cobranças recorrentes são interrompidas imediatamente
- O cliente não será mais cobrado enquanto a assinatura estiver suspensa
- A assinatura mantém seu histórico e configurações originais
- Pode ser reativada a qualquer momento através da rota de reativação

**Observações importantes:**
- A suspensão é diferente do cancelamento, pois permite reativação posterior
- O período de suspensão não conta para a duração total da assinatura
- O cliente mantém acesso aos benefícios até o final do período já pago
- A reativação pode ser feita a qualquer momento, retomando as cobranças no próximo ciclo

Suspender assinatura

Reativa uma assinatura que está suspensa. Ao reativar uma assinatura, os cobramentos automáticos serão retomados de acordo com o plano e periodicidade configurados.

Reativar assinatura

Cancela uma assinatura existente. Após o cancelamento, a assinatura não poderá mais ser reativada.

Introdução e Aspectos Gerais

​Ambiente Sandbox

​Características do Ambiente Sandbox

​Ambiente de Produção

​Características do Ambiente de Produção

​Recomendações

​Fluxo de Desenvolvimento Recomendado