API de pagamentos para aplicativos de agendamento no Parque Edu Chaves - ViperPay

Seu aplicativo de agendamento no Parque Edu Chaves recebe dezenas de solicitações por dia, mas o pagamento ainda depende de transferência manual, maquininha emprestada ou “combinamos na hora”? Esse gap entre a reserva confirmada e o dinheiro no caixa gera inadimplência, desgaste com prestadores e noites em claro conciliando planilhas.

A integração nativa de uma API de pagamentos resolve isso na raiz: o cliente agenda, paga no mesmo fluxo (Pix, boleto ou cartão) e a plataforma já divide os valores entre prestadores e comissão — tudo auditável em tempo real. Neste artigo, mostramos o passo a passo técnico e operacional para implementar esse motor financeiro no seu app.

Antes de mergulhar no código, vale alinhar expectativas: a ViperPay não é apenas um gateway; é uma camada de orquestração financeira que cuida de antifraude, split, conciliação e emissão de relatórios contábeis prontos para o seu contador. Vamos direto ao que importa.

Arquitetura de integração: onde a API se encaixa no seu fluxo

O ponto de partida é mapear cada momento em que dinheiro muda de hands no seu aplicativo. No cenário típico de agendamento no Parque Edu Chaves, existem pelo menos quatro gatilhos financeiros:

1. Confirmação do agendamento — pagamento integral ou sinal (ex.: 30% na reserva, 70% no atendimento)
2. Remarcação com diferença de valor — cobrança complementar ou reembolso parcial
3. Cancelamento com política de reembolso — devolução automática conforme regra de negócio (ex.: 100% até 24h, 50% até 2h)
4. Pagamento no local (opcional) — QR Code Pix dinâmico gerado pelo app do prestador

Cada gatilho corresponde a uma chamada à API ViperPay (POST /charges para cobranças, POST /refunds para reembolsos). A idempotência é obrigatória: envie sempre um idempotency_key único por tentativa (ex.: booking_12345_attempt_1) para evitar cobranças duplicadas se a rede falhar e o app retentar.

Configurando o split de pagamentos entre plataforma e prestadores

O split é o coração financeiro de um marketplace de agendamento. Na ViperPay, você cria regras de divisão vinculadas a cada charge. Exemplo prático para um app de serviços no Parque Edu Chaves:

{
  "amount": 25000,
  "currency": "BRL",
  "payment_method": "pix",
  "split_rules": [
    {
      "recipient_id": "rec_prestador_joao",
      "type": "percentage",
      "value": 70
    },
    {
      "recipient_id": "rec_plataforma",
      "type": "percentage",
      "value": 25
    },
    {
      "recipient_id": "rec_fundo_reserva",
      "type": "percentage",
      "value": 5
    }
  ],
  "metadata": {
    "booking_id": "bk_parque_edu_789",
    "service_type": "desentupimento",
    "neighborhood": "Parque Edu Chaves"
  }
}

O recipient_id de cada prestador é cadastrado previamente via POST /recipients com dados bancários e KYC validado. A plataforma define as regras uma única vez (ou por categoria de serviço) e a API aplica automaticamente em cada transação. A liquidação segue o prazo do método: D+1 para Pix, D+2 para boleto, D+30 para cartão de crédito.

Webhooks: o sistema nervoso da sua automação

Não faça polling. Configure webhooks para receber eventos em tempo real e atualizar o status do agendamento no seu banco de dados. Os quatro eventos essenciais:

Cada webhook traz o charge_id e o metadata.booking_id que você enviou na criação. Use esse ID para reconciliar sem ambiguidade. Valide a assinatura HMAC-SHA256 do cabeçalho X-ViperPay-Signature para garantir autenticidade.

Conciliação automática: do extrato ao balanço sem planilhas

A maior dor de quem opera agendamentos no Parque Edu Chaves não é receber — é provar que recebeu e separar o que é de cada um. O dashboard ViperPay gera relatórios de conciliação com três granularidades:

• Por transação: cada linha mostra booking_id, prestador_id, valor_bruto, taxa_gateway, valor_liquido_prestador, comissao_plataforma, data_liquidacao_prevista, status_liquidacao
• Por prestador: consolidação semanal/mensal com totais e pendentes de chargeback
• Por método: volume Pix vs boleto vs cartão, taxa média efetiva, tempo médio de liquidação

Esses relatórios são exportáveis em CSV/XLSX e também acessíveis via API (GET /reports/conciliation?start=2024-01-01&end=2024-01-31&group_by=recipient). Seu contador importa direto no ERP; seu financeiro acompanha o fluxo de caixa diário sem digitar uma vírgula.

Antifraude calibrado para serviços locais

Serviços de agendamento no Parque Edu Chaves têm perfil de risco diferente de e-commerce de varejo: ticket médio alto, recorrência baixa, prestador físico no endereço do cliente. O motor antifraude ViperPay permite regras customizadas:

• Velocidade: bloquear se mesmo CPF tentar 3 agendamentos pagos em 10 minutos
• Geolocalização: alerta se IP do pagador estiver a >50km do endereço do serviço (exceto se for agendamento para terceiros)
• Dispositivo: score de risco baseado em fingerprint do device (novo device + cartão novo = verificação manual)
• Lista negativa/positiva: CPFs/CNPs bloqueados ou pré-aprovados por histórico

Tudo configurável no painel sem deploy de código. Quando uma transação cai em “revisão manual”, o webhook charge.under_review avisa seu app para segurar a liberação do prestador até a decisão final (média de 15 min em horário comercial).

Checklist de homologação antes de ir para produção

1. Criar todos os recipients (prestadores + plataforma + fundo de reserva) no sandbox e validar dados bancários
2. Implementar fluxo completo: criar cobrança → pagar com cartão de teste aprovado → conferir webhook charge.paid → verificar split no dashboard
3. Testar reembolso total e parcial (POST /refunds) e confirmar estorno no split dos recipients
4. Simular chargeback no sandbox e validar fluxo de evidências e bloqueio de split
5. Rodar relatório de conciliação por booking_id e conferir se cada agendamento tem rastreabilidade 1:1
6. Validar emissão de NFS-e acionada pelo webhook charge.paid (integração com seu emissor fiscal)
7. Testar cenário de falha de rede: reenviar mesma idempotency_key e confirmar que não criou cobrança duplicada
8. Medir latência P95 da API no sandbox (meta: < 800 ms para POST /charges)
9. Aprovar com a equipe de suporte ViperPay a liberação das chaves de produção

Próximos passos: escalando a operação financeira

Com a integração rodando, o próximo nível é automatizar a gestão de inadimplência e recorrência. Se seu app no Parque Edu Chaves passa a oferecer planos de manutenção preventiva (ex.: limpeza de caixa de gordura trimestral), a API de cobrança recorrente da ViperPay cria assinaturas com retentativa automática e atualização de cartão via tokenização. Veja como implementar em API de cobrança recorrente fideliza cliente de corte longo no Ipiranga.

Para equipes de campo que precisam receber no local, o checkout transparente com QR Code Pix dinâmico elimina a maquininha. Veja o caso prático em Checkout transparente reduz abandono em penteado de madrinha na Liberdade.

E se a conciliação ainda toma tempo do seu financeiro, a conciliação bancária instantânea resolve com extrato unificado. Detalhes em Conciliação bancária instantânea para equipes de campo em Santa Maria Contagem.

Para saber como desentupir cano no Parque Edu Chaves, consulte desentupidora 24h no Parque Edu Chaves SP.

Implantar a API de pagamentos no seu app de agendamento transforma a financeira de um gargalo em vantagem competitiva: prestadores recebem no prazo, a plataforma escala sem contratar analistas de conciliação, e o cliente final paga com a mesma fluidez de pedir um transporte por app. Comece pelo sandbox hoje — a primeira transação em produção sai ainda esta semana.

Checklist prático

Perguntas frequentes