Integração com IA

Use esta página como contexto inicial ao gerar uma integração com a Flare Payments. Ela reúne os contratos essenciais da API pública, exemplos de cobrança e regras para confirmação de pagamentos.

Documentação completa

Consulte os guias e as referências de cada endpoint.

Índice para LLMs

Acesse o conteúdo da documentação em formato otimizado para modelos de linguagem.

Contrato essencial

Estes valores definem o contrato base de qualquer integração:

Item	Valor
Base URL	`https://api.flarepayments.com/v1`
Autenticação	`Authorization: Bearer YOUR_API_KEY`
Chave secreta	Prefixo `sk_live_`
Unidade de cobrança	Centavos, por exemplo `1000` = R$ 10,00
Identificador da cobrança	`uuid`
Confirmação de pagamento	Webhook ou consulta de status

Execute chamadas autenticadas somente no backend. Nunca exponha uma chave sk_live_ no navegador, em aplicativos client-side, repositórios públicos ou logs.

Regras para assistentes de IA

Siga estas regras ao gerar código para a API:

Use somente endpoints e campos documentados pela Flare
Envie valores de cobrança em centavos
Use a chave sk_live_ para autenticação
Não use uma chave pk_live_ para autenticar requisições
Salve o uuid retornado ao criar uma cobrança
Considere o pagamento confirmado somente após status: "paid"
Prefira webhooks para confirmação automática
Use GET /charges/{uuid}/status para consultas periódicas
Trate erros pelo campo error.code
Não crie parâmetros, respostas, eventos ou endpoints ausentes da documentação

Quando houver divergência, use a página específica do endpoint como fonte principal.

Autenticar requisições

Envie a chave secreta no header Authorization:

Authorization: Bearer YOUR_API_KEY

Este exemplo consulta o saldo autenticado:

curl https://api.flarepayments.com/v1/balance \\
  --header 'Authorization: Bearer YOUR_API_KEY'

Status	Código	Motivo
`401`	`missing_authorization`	Header `Authorization` ausente
`401`	`invalid_authorization`	Formato de autenticação inválido
`401`	`invalid_api_key`	Chave de API não encontrada
`403`	`api_key_disabled`	Chave desativada
`403`	`api_key_revoked`	Chave revogada
`429`	`rate_limit_exceeded`	Limite de requisições excedido

Endpoints disponíveis

Use este catálogo para selecionar o endpoint correto:

Operação	Método e caminho	Resultado
Criar cobrança	`POST /charges`	Cria uma cobrança Pix ou boleto
Consultar cobrança	`GET /charges/{uuid}`	Retorna os dados da cobrança
Consultar status	`GET /charges/{uuid}/status`	Retorna `uuid`, `status` e `paid`
Consultar saldo	`GET /balance`	Retorna saldos disponível e pendente
Listar transações	`GET /transactions`	Retorna o histórico paginado

Saques não estão disponíveis pela API pública. Solicite saques pelo Dashboard da Flare.

Criar uma cobrança

Envie POST https://api.flarepayments.com/v1/charges com Content-Type: application/json. O limite documentado é de 60 requisições por minuto.

Pix
Boleto

Campos da cobrança Pix

O corpo aceita os seguintes campos:

Campo	Tipo	Obrigatório	Regra
`amount`	integer	Sim	Valor mínimo de `500` centavos
`payment_method`	string	Sim	Use `pix`
`description`	string	Não	Descrição da cobrança
`customer`	object	Não	Dados do pagador
`customer.name`	string	Não	Nome completo
`customer.email`	string	Não	E-mail
`customer.document`	string	Não	CPF ou CNPJ

Crie uma cobrança Pix:

curl --request POST \\
  --url https://api.flarepayments.com/v1/charges \\
  --header 'Authorization: Bearer YOUR_API_KEY' \\
  --header 'Content-Type: application/json' \\
  --data '{
    "amount": 1000,
    "payment_method": "pix",
    "description": "Pedido #1234"
  }'

A API responde com 201 Created:

{
  "success": true,
  "uuid": "54e2b712-aca0-4230-b69a-d6dd8542c925",
  "amount": 1000,
  "expires_at": "2026-09-13T23:59:59Z",
  "pix_copy_paste": "00020101021226..."
}

Campos da cobrança por boleto

O boleto exige os dados do pagador e o endereço de cobrança:

Campo	Tipo	Obrigatório	Regra
`amount`	integer	Sim	Valor mínimo de `500` centavos
`payment_method`	string	Sim	Use `boleto`
`description`	string	Não	Descrição da cobrança
`customer.name`	string	Sim	Nome completo
`customer.email`	string	Sim	E-mail
`customer.document`	string	Sim	CPF ou CNPJ válido
`customer.phone`	string	Sim	DDD e telefone, com 10 ou 11 dígitos
`billing_address.zip`	string	Sim	CEP com 8 dígitos
`billing_address.state`	string	Sim	UF com 2 letras
`billing_address.city`	string	Sim	Cidade
`billing_address.street`	string	Sim	Rua ou avenida
`billing_address.neighborhood`	string	Sim	Bairro
`billing_address.number`	string	Sim	Número
`billing_address.complement`	string	Não	Complemento

Crie uma cobrança por boleto:

curl --request POST \\
  --url https://api.flarepayments.com/v1/charges \\
  --header 'Authorization: Bearer YOUR_API_KEY' \\
  --header 'Content-Type: application/json' \\
  --data '{
    "amount": 1000,
    "payment_method": "boleto",
    "description": "Pedido #1234",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "document": "52998224725",
      "phone": "11999999999"
    },
    "billing_address": {
      "zip": "01001000",
      "state": "SP",
      "city": "São Paulo",
      "street": "Praça da Sé",
      "neighborhood": "Sé",
      "number": "100",
      "complement": "Apto 10"
    }
  }'

A API responde com 201 Created:

{
  "uuid": "54e2b712-aca0-4230-b69a-d6dd8542c925",
  "success": true,
  "boleto_url": "https://example.com/boleto.pdf",
  "barcode": "001905009...",
  "amount": 1000,
  "expires_at": "2026-09-16T23:59:59Z"
}

Consultar uma cobrança

Consulte GET /charges/{uuid} para obter os dados correspondentes ao método de pagamento:

curl --request GET \\
  --url https://api.flarepayments.com/v1/charges/54e2b712-aca0-4230-b69a-d6dd8542c925 \\
  --header 'Authorization: Bearer YOUR_API_KEY'

Pix
Boleto

{
  "success": true,
  "uuid": "54e2b712-aca0-4230-b69a-d6dd8542c925",
  "amount": 1000,
  "status": "paid",
  "expires_at": "2026-03-05T19:14:48.549Z",
  "pix_copy_paste": "00020101021226..."
}

{
  "success": true,
  "uuid": "54e2b712-aca0-4230-b69a-d6dd8542c925",
  "amount": 1000,
  "status": "pending",
  "expires_at": "2026-03-08T23:59:59.000Z",
  "boleto_url": "https://example.com/boleto.pdf",
  "barcode": "00190.00009 01234.567890 12345.678901 1 99990000001000"
}

Os status documentados são pending, paid, expired e failed.

Consultar o status

Use GET /charges/{uuid}/status quando precisar consultar o status periodicamente:

curl --request GET \\
  --url https://api.flarepayments.com/v1/charges/54e2b712-aca0-4230-b69a-d6dd8542c925/status \\
  --header 'Authorization: Bearer YOUR_API_KEY'

{
  "uuid": "54e2b712-aca0-4230-b69a-d6dd8542c925",
  "status": "pending",
  "paid": false
}

Confirmar pagamentos com webhooks

Webhooks notificam seu backend sobre mudanças no pagamento. Responda com HTTP 200 em até 5 segundos e processe o evento de forma assíncrona.

Evento	Uso
`charge.paid`	Confirma uma cobrança paga
`charge.expired`	Informa que a cobrança expirou
`charge.failed`	Informa falha no processamento
`transfer.completed`	Informa a conclusão de um saque
`transfer.failed`	Informa falha em um saque

O mesmo evento pode ser entregue mais de uma vez. Use o uuid da cobrança para impedir processamento duplicado. Este exemplo responde antes de iniciar o processamento:

app.post('/webhooks/flare', express.json(), (req, res) => {
  const { event, data } = req.body;

  res.status(200).json({ received: true });
  processarEvento(event, data).catch(console.error);
});

Exemplo de charge.paid:

{
  "event": "charge.paid",
  "data": {
    "uuid": "54e2b712-aca0-4230-b69a-d6dd8542c925",
    "amount": 1000,
    "status": "paid",
    "description": "Pedido #1234",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com"
    },
    "paid_at": "2026-03-05T18:16:22.000Z",
    "created_at": "2026-03-05T18:14:48.552Z"
  }
}

Consultar saldo

Consulte GET /balance para obter os saldos disponível e pendente:

curl https://api.flarepayments.com/v1/balance \\
  --header 'Authorization: Bearer YOUR_API_KEY'

Os campos available[].amount e pending[].amount usam centavos. Os valores dentro de summary usam reais.

Listar transações

Consulte GET /transactions para obter o histórico paginado:

curl --request GET \\
  --url 'https://api.flarepayments.com/v1/transactions?limit=20' \\
  --header 'Authorization: Bearer YOUR_API_KEY'

Parâmetro	Tipo	Regra
`limit`	integer	De 1 a 100, padrão 10
`starting_after`	string	UUID do último item da página anterior
`type`	string	`charge` ou `withdrawal`
`status`	string	Filtra pelo status
`created[gte]`	ISO 8601	Data inicial
`created[lte]`	ISO 8601	Data final

Se has_more for true, envie o uuid do último item em starting_after.

Tratar erros

Trate o código estável em error.code:

{
  "error": {
    "code": "invalid_amount",
    "message": "amount deve ser um inteiro positivo em centavos"
  }
}

Não dependa apenas do texto em error.message. Alguns erros incluem campos adicionais.

Implementar uma cobrança Pix

Use este fluxo no backend:

Crie a cobrança

Envie POST /v1/charges com amount em centavos e payment_method: “pix”.

Salve o UUID

Persista o campo uuid retornado pela Flare.

Exiba o código Pix

Envie pix_copy_paste ao cliente.

Receba o webhook

Responda com HTTP 200 e processe charge.paid uma única vez por uuid.

Confirme o pagamento

Libere o produto ou serviço somente após receber status: “paid”.

Exemplo em TypeScript

Este código cria uma cobrança Pix no backend:

const apiKey = process.env.FLARE_API_KEY;

const response = await fetch(
  'https://api.flarepayments.com/v1/charges',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: 1000,
      payment_method: 'pix',
      description: 'Pedido #1234',
    }),
  },
);

const data = await response.json();

if (!response.ok) {
  throw new Error(data?.error?.code ?? 'flare_request_failed');
}

Documentação completa

Índice para LLMs

Contrato essencial

Regras para assistentes de IA

Autenticar requisições

Endpoints disponíveis

Criar uma cobrança

Campos da cobrança Pix

Campos da cobrança por boleto

Consultar uma cobrança

Consultar o status

Confirmar pagamentos com webhooks

Consultar saldo

Listar transações

Tratar erros

Implementar uma cobrança Pix

Exemplo em TypeScript

Checklist da integração

Fontes oficiais

Criar cobrança

Consultar cobrança

Status da cobrança

Consultar saldo

Listar transações

Eventos de webhook

Documentação completa

Índice para LLMs

​Contrato essencial

​Regras para assistentes de IA

​Autenticar requisições

​Endpoints disponíveis

​Criar uma cobrança

​Campos da cobrança Pix

​Campos da cobrança por boleto

​Consultar uma cobrança

​Consultar o status

​Confirmar pagamentos com webhooks

​Consultar saldo

​Listar transações

​Tratar erros

​Implementar uma cobrança Pix

​Exemplo em TypeScript

​Checklist da integração

​Fontes oficiais

Criar cobrança

Consultar cobrança

Status da cobrança

Consultar saldo

Listar transações

Eventos de webhook

Contrato essencial

Regras para assistentes de IA

Autenticar requisições

Endpoints disponíveis

Criar uma cobrança

Campos da cobrança Pix

Campos da cobrança por boleto

Consultar uma cobrança

Consultar o status

Confirmar pagamentos com webhooks

Consultar saldo

Listar transações

Tratar erros

Implementar uma cobrança Pix

Exemplo em TypeScript

Checklist da integração

Fontes oficiais