Visão geral da API

A API do Gateway Cyclopay permite integrar pagamentos a sites, aplicativos e sistemas de gestão. Com ela, sua aplicação pode criar e consultar Vendas, acompanhar Transações e executar operações posteriores, como capturas e reembolsos, conforme o meio de pagamento e os recursos habilitados.

A comunicação utiliza requisições HTTP e respostas documentadas por endpoint. Esta página apresenta os conceitos essenciais e indica por onde começar. Para parâmetros, estruturas JSON e exemplos completos, consulte a operação correspondente na Referência da API.

Como a API está organizada

Os recursos são separados por finalidade:

Recurso	O que permite fazer
Vendas (`charges`)	Criar, consultar e gerenciar cobranças.
Transações (`transactions`)	Consultar tentativas e operações de pagamento associadas a uma Venda.
Cartão de crédito e débito	Processar pagamentos e utilizar funcionalidades disponíveis para cada modalidade, como captura, 3DS e tokenização.
Pix e Boleto	Gerar e acompanhar cobranças pelos respectivos meios de pagamento.
Checkout e Link de Pagamento	Utilizar páginas de pagamento e gerar links de cobrança.
SmartForm	Integrar a coleta de dados de pagamento por cartão à experiência da sua aplicação.
Split de Pagamento	Distribuir valores de pagamentos entre vendedores, conforme as regras configuradas.
Webhooks	Receber notificações de eventos em um endpoint do seu sistema.

Os endpoints indicam o método HTTP aplicável a cada operação. Em geral, GET consulta dados e POST cria recursos ou executa ações. Consulte a documentação de cada rota para identificar outros métodos admitidos.

Disponibilidade dos recursos

Nem todas as operações são aplicáveis a todos os meios de pagamento. Verifique os requisitos e as restrições indicados em cada endpoint.

Conceitos essenciais: Venda e Transação

Na API, uma Venda é representada pelo recurso charge, acessado pelos endpoints de /charges. Ela reúne os dados da cobrança e sua situação consolidada.

Uma Transação (transaction) representa uma tentativa ou operação de pagamento vinculada à Venda. Uma mesma Venda pode ter várias Transações, por exemplo, quando há uma tentativa recusada seguida de outra tentativa de pagamento.

Nas respostas de Venda, as operações relacionadas podem aparecer no array transactions[].

Campo	Como interpretar
`charge.status`	Situação consolidada da Venda.
`transaction.status`	Resultado resumido de uma Transação.
`transaction.detailed_status`	Etapa detalhada do processamento da Transação.

Não confunda sucesso da requisição com pagamento aprovado. Uma resposta HTTP 200 ou 201 indica o resultado da operação HTTP, mas a situação financeira deve ser verificada nos estados da Venda e das Transações.

Saiba mais em Venda e Transação e Status da Transação.

Ambientes: Sandbox e Live

A Cyclopay disponibiliza ambientes separados para testes e produção.

Ambiente	URL base da API	Finalidade
Sandbox	`https://gateway-sandbox.cyclopay.com/v1/`	Desenvolvimento e homologação sem movimentação financeira real.
Live	`https://gateway.cyclopay.com/v1/`	Processamento de operações reais.

Cada ambiente utiliza credenciais e configurações próprias. Não reutilize uma chave do Sandbox no ambiente Live, nem o contrário.

Consulte Ambientes (Live e Sandbox) e Cartões de Teste.

Autenticação

As operações autenticadas exigem uma chave de API enviada no cabeçalho HTTP api_key. A credencial pode ser obtida no BackOffice Cyclopay, na empresa correspondente ao ambiente utilizado.

Exemplo: consultar Vendas no Sandbox

curl --request GET \
  --url https://gateway-sandbox.cyclopay.com/v1/charges \
  --header 'api_key: SUA_API_KEY'

Substitua SUA_API_KEY pela credencial do seu ambiente de testes. Armazene-a no servidor ou em um gerenciador de segredos e não a exponha no código do navegador nem em repositórios públicos.

Veja como obter e configurar suas credenciais em Chaves e Autenticação da API.

Fluxo básico de uma integração

Escolha a modalidade de integração. Avalie API Direta, SmartForm e Checkout/Link de Pagamento conforme a experiência desejada.
Configure o Sandbox. Utilize a URL base e a chave de API desse ambiente.
Crie uma Venda. Para iniciar uma cobrança pela API, consulte a operação POST /charges e os parâmetros do meio de pagamento escolhido.
Interprete o resultado. Verifique o corpo da resposta e os estados da Venda e das Transações. Em fluxos como Pix e Boleto, o pagamento pode permanecer aguardando confirmação.
Acompanhe atualizações. Utilize consultas à API e, quando aplicável, webhooks. Valide também recusas, erros e operações posteriores antes de ir para produção.

A integração com cartão, Pix, Boleto e Checkout possui particularidades descritas nas respectivas seções.

Comece pelo Sandbox

Realize sua primeira cobrança de teste e acompanhe o resultado antes de utilizar credenciais de produção.

Respostas e tratamento de erros

Para tratar corretamente o retorno da API, considere o código HTTP, o corpo da resposta e o estado do recurso. Erros de validação e de comunicação não devem ser confundidos com uma Transação recusada.

Use estas páginas como referência:

Próximos passos

Se você está começando, siga esta ordem:

A Referência da API reúne os contratos técnicos de cada operação. Para fluxos completos de implementação, consulte também a seção Exemplos Práticos.