Guia do Desenvolvedor: Integre Pagamentos BeInfi via API

Guia completo para integrar a API de pagamentos da BeInfi — chaves de API, webhooks, tipos de eventos e exemplos em TypeScript.

Se você está construindo um app, SaaS ou marketplace que precisa processar pagamentos, a API da BeInfi tem tudo que você precisa. Este guia cobre gerenciamento de chaves, criação de pagamentos, configuração de webhooks e boas práticas — tudo com exemplos em TypeScript prontos para usar.

Começando

Pré-requisitos

Uma conta BeInfi (cadastre-se aqui)
Node.js 18+ ou qualquer ambiente que suporte fetch
Conhecimento básico de APIs REST e TypeScript

URL Base da API

https://api.beinfi.com/v1

Todas as requisições precisam de autenticação e usar Content-Type: application/json.

Gerenciamento de Chaves de API

Gerando Chaves

Faça login no painel da BeInfi
Navegue até Configurações > Chaves de API
Clique em Gerar Nova Chave
Escolha as permissões (somente leitura, escrita ou acesso total)
Copie a chave imediatamente — ela não será exibida novamente

Tipos de Chave

Tipo	Caso de Uso	Permissões
Chave Secreta	Operações server-side	Acesso total à API
Chave Pública	Client-side (limitada)	Somente leitura, iniciar pagamentos

Boas Práticas de Segurança

Nunca exponha chaves secretas em código client-side ou repositórios públicos
Use variáveis de ambiente para armazenar chaves
Faça rotação regularmente — mensalmente em produção, sempre que um membro sair do time
Use chaves separadas para desenvolvimento e produção

// Armazene chaves em variáveis de ambiente
const API_KEY = process.env.BEINFI_SECRET_KEY;

if (!API_KEY) {
  throw new Error('BEINFI_SECRET_KEY não está configurada');
}

Autenticação

Toda requisição precisa de um Bearer token no header Authorization:

const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json',
};

Chaves inválidas ou expiradas retornam 401 Unauthorized.

Criando Pagamentos

Criar um Link de Pagamento

interface CriarPagamentoRequest {
  amount: number;
  currency: 'BRL';
  description: string;
  redirect_url?: string;
  metadata?: Record<string, string>;
  expires_at?: string; // ISO 8601
}

interface PagamentoResponse {
  id: string;
  status: 'pending' | 'completed' | 'failed' | 'expired';
  amount: number;
  currency: string;
  payment_url: string;
  pix_code?: string;
  created_at: string;
  expires_at: string | null;
}

async function criarPagamento(
  dados: CriarPagamentoRequest
): Promise<PagamentoResponse> {
  const response = await fetch('https://api.beinfi.com/v1/payments', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(dados),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Falha ao criar pagamento: ${error.message}`);
  }

  return response.json();
}

// Uso
const pagamento = await criarPagamento({
  amount: 49.90,
  currency: 'BRL',
  description: 'Plano Pro - Assinatura Mensal',
  redirect_url: 'https://seuapp.com.br/sucesso',
  metadata: {
    user_id: 'usr_12345',
    plan: 'pro_mensal',
  },
});

console.log(`URL do Pagamento: ${pagamento.payment_url}`);
console.log(`Código PIX: ${pagamento.pix_code}`);

Consultar Status de Pagamento

async function buscarPagamento(
  pagamentoId: string
): Promise<PagamentoResponse> {
  const response = await fetch(
    `https://api.beinfi.com/v1/payments/${pagamentoId}`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
      },
    }
  );

  if (!response.ok) {
    throw new Error(
      `Falha ao buscar pagamento: ${response.statusText}`
    );
  }

  return response.json();
}

// Consultar status (ou use webhooks — recomendado)
const status = await buscarPagamento('pay_abc123');
console.log(`Status do pagamento: ${status.status}`);

Listar Pagamentos

interface ListarPagamentosParams {
  status?: 'pending' | 'completed' | 'failed' | 'expired';
  limit?: number;
  offset?: number;
  created_after?: string;
  created_before?: string;
}

async function listarPagamentos(
  params: ListarPagamentosParams = {}
): Promise<{ data: PagamentoResponse[]; total: number }> {
  const searchParams = new URLSearchParams();
  Object.entries(params).forEach(([key, value]) => {
    if (value !== undefined) searchParams.set(key, String(value));
  });

  const response = await fetch(
    `https://api.beinfi.com/v1/payments?${searchParams}`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
      },
    }
  );

  return response.json();
}

Configuração de Webhooks

Webhooks permitem que sua aplicação receba notificações em tempo real sobre eventos de pagamento. Essa é a abordagem recomendada em vez de polling.

Configurando Webhooks

Vá em Configurações > Webhooks no seu painel
Clique em Adicionar Endpoint
Insira a URL do seu endpoint (precisa ser HTTPS)
Selecione os eventos que deseja receber
Copie o segredo de assinatura do webhook

Tipos de Eventos

Evento	Descrição	Quando Dispara
`payment.created`	Novo pagamento iniciado	Cliente inicia checkout
`payment.completed`	Pagamento confirmado	Fundos recebidos com sucesso
`payment.failed`	Tentativa de pagamento falhou	PIX expirado, erro no processamento
`payment.expired`	Link de pagamento expirou	Passou do timestamp `expires_at`
`payment.refunded`	Reembolso processado	Reembolso manual ou via API
`subscription.created`	Nova assinatura iniciada	Primeiro pagamento confirmado
`subscription.renewed`	Assinatura renovada	Pagamento recorrente bem-sucedido
`subscription.cancelled`	Assinatura cancelada	Cancelamento pelo cliente ou merchant

Estrutura do Payload

interface WebhookPayload {
  id: string;
  event: string;
  created_at: string;
  data: {
    payment_id: string;
    amount: number;
    currency: string;
    status: string;
    metadata: Record<string, string>;
  };
}

Processando Webhooks

import { createHmac } from 'crypto';

const WEBHOOK_SECRET = process.env.BEINFI_WEBHOOK_SECRET!;

function verificarAssinatura(
  payload: string,
  assinatura: string
): boolean {
  const esperado = createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');

  return assinatura === `sha256=${esperado}`;
}

// Exemplo com Express.js
app.post('/webhooks/beinfi', express.raw({ type: 'application/json' }), (req, res) => {
  const assinatura = req.headers['x-beinfi-signature'] as string;
  const payload = req.body.toString();

  if (!verificarAssinatura(payload, assinatura)) {
    return res.status(401).json({ error: 'Assinatura inválida' });
  }

  const evento: WebhookPayload = JSON.parse(payload);

  switch (evento.event) {
    case 'payment.completed':
      processarPagamentoCompleto(evento.data);
      break;
    case 'payment.failed':
      processarPagamentoFalho(evento.data);
      break;
    case 'subscription.renewed':
      processarRenovacao(evento.data);
      break;
    default:
      console.log(`Tipo de evento não tratado: ${evento.event}`);
  }

  // Sempre retorne 200 para confirmar recebimento
  res.status(200).json({ received: true });
});

async function processarPagamentoCompleto(
  data: WebhookPayload['data']
) {
  // Atualize seu banco de dados
  await db.pedidos.update({
    where: { paymentId: data.payment_id },
    data: { status: 'pago' },
  });

  // Libere acesso, envie email de confirmação, etc.
  await liberarAcesso(data.metadata.user_id, data.metadata.plan);
  await enviarEmailConfirmacao(data.metadata.user_id);
}

Boas Práticas de Webhooks

Sempre verifique assinaturas antes de processar eventos
Retorne 200 rapidamente — faça processamento pesado de forma assíncrona
Trate duplicatas — eventos de webhook podem ser enviados mais de uma vez
Registre tudo — armazene payloads brutos para debugging
Configure retry handling — a BeInfi reenvia entregas com falha usando backoff exponencial

// Idempotência: previna processamento duplicado
async function processarWebhook(evento: WebhookPayload) {
  const existente = await db.webhookEvents.findUnique({
    where: { eventId: evento.id },
  });

  if (existente) {
    console.log(`Evento ${evento.id} já processado, pulando`);
    return;
  }

  // Processe o evento
  await tratarEvento(evento);

  // Registre que processamos
  await db.webhookEvents.create({
    data: { eventId: evento.id, processedAt: new Date() },
  });
}

Tratamento de Erros

A API usa códigos de status HTTP padrão:

Código	Significado	Ação
`200`	Sucesso	Processe a resposta
`400`	Requisição Inválida	Verifique o body da requisição
`401`	Não Autorizado	Verifique sua chave de API
`404`	Não Encontrado	Verifique o ID do recurso
`422`	Erro de Validação	Verifique campos obrigatórios
`429`	Rate Limited	Aguarde e tente novamente
`500`	Erro do Servidor	Retry com backoff exponencial

class BeInfiAPIError extends Error {
  constructor(
    public statusCode: number,
    public errorCode: string,
    message: string
  ) {
    super(message);
    this.name = 'BeInfiAPIError';
  }
}

async function requisicaoAPI<T>(
  endpoint: string,
  options: RequestInit = {}
): Promise<T> {
  const response = await fetch(`https://api.beinfi.com/v1${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new BeInfiAPIError(
      response.status,
      error.code,
      error.message
    );
  }

  return response.json();
}

Rate Limits

A API aplica limites de taxa para garantir estabilidade:

Plano	Limite
Free	60 requisições/minuto
Pro	300 requisições/minuto
Enterprise	Limites customizados

Respostas com rate limit incluem headers com informações de reset:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 12
X-RateLimit-Reset: 1709251200

Exemplo Completo de Integração

Uma rota de API completa em Next.js que cria pagamento e trata o webhook:

// app/api/checkout/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const { planId, userId } = await req.json();

  const planos: Record<string, { nome: string; preco: number }> = {
    starter: { nome: 'Plano Starter', preco: 29.90 },
    pro: { nome: 'Plano Pro', preco: 79.90 },
    business: { nome: 'Plano Business', preco: 199.90 },
  };

  const plano = planos[planId];
  if (!plano) {
    return NextResponse.json(
      { error: 'Plano inválido' },
      { status: 400 }
    );
  }

  const pagamento = await requisicaoAPI<PagamentoResponse>(
    '/payments',
    {
      method: 'POST',
      body: JSON.stringify({
        amount: plano.preco,
        currency: 'BRL',
        description: `${plano.nome} - Mensal`,
        redirect_url: `${process.env.NEXT_PUBLIC_URL}/dashboard?payment=success`,
        metadata: {
          user_id: userId,
          plan_id: planId,
        },
      }),
    }
  );

  return NextResponse.json({
    paymentUrl: pagamento.payment_url,
    pixCode: pagamento.pix_code,
  });
}

Próximos Passos

Com pagamentos funcionando, explore:

Gerenciamento de assinaturas para cobranças recorrentes
Portal do cliente usando o endpoint de listagem de pagamentos
Monitoramento com logs de eventos de webhook
Fluxos de reembolso pela API de refunds

A API da BeInfi foi feita para desenvolvedores que querem infraestrutura de pagamentos que simplesmente funciona. Endpoints limpos, webhooks previsíveis e design TypeScript-first. Comece a construir em beinfi.com.