[Pix Automático na Vindi] Guia Rápido de Integração (API)
Nesta etapa inicial, a oferta do Pix Automático é disponibilizada exclusivamente via integração por API.
Pré-requisitos: É indispensável que o "Gateway de Pix Automático" esteja ativo e o método de pagamento devidamente habilitado na conta da plataforma.
Dados Cadastrais do Pagador: Para garantir a validação e a execução correta da cobrança, as informações cadastrais devem estar íntegras no sistema. É obrigatório que o cadastro do pagador contenha o número do documento (CPF ou CNPJ) devidamente preenchido; a ausência ou inconsistência deste dado resultará em falha na transação.
Criação da Assinatura (POST /v1/subscriptions): Para o Pix Automático, a combinação dos campos na requisição define se a primeira cobrança será imediata ou agendada para o futuro.
Parâmetros Obrigatórios
payment_method_code: enviar como "pix_automatic".
billing_trigger_type: enviar como "beginning_of_period".
start_at: data de início no formato YYYY-MM-DD. (Se omitido, o sistema assume a configuração padrão do plano).
Cenários de Cobrança
Cenário A: Cobrança Imediata (First Payment)
Utilizado quando o cliente paga a primeira parcela no ato da contratação. Envie a data de hoje no campo start_at:
{
"plan_id": 12345,
"customer_id": 67890,
"payment_method_code": "pix_automatic",
"billing_trigger_type": "beginning_of_period",
"start_at": "2026-05-19" // data atual
}
Uma cobrança imediata é gerada no momento da autorização;
O sistema solicita o consentimento para as próximas recorrências automaticamente;
O cliente autoriza o pagamento atual e todas as cobranças futuras em um único fluxo.
Cenário B: Agendamento Futuro
Utilizado quando o cliente contrata hoje, mas o primeiro pagamento ocorrerá em data futura:
{
"plan_id": 12345,
"customer_id": 67890,
"payment_method_code": "pix_automatic",
"billing_trigger_type": "beginning_of_period",
"start_at": "2026-06-08" // D-2: para cobrar no dia 10, agende para o dia 08
}
📅 REGRA D-2: Se o vencimento desejado é o dia 10, o start_at deve ser o dia 08. O agendamento no banco ocorre sempre 2 dias antes da liquidação.
O sistema registra o consentimento imediatamente;
O cliente autoriza o débito futuro no app do banco;
Nenhum valor é cobrado no ato da contratação;
A primeira cobrança ocorre na data configurada em start_at.
4. Regras de Agendamento e Consentimento
Data do Plano: Para recorrências precisas, configure a data de cobrança do plano como “Exatamente no dia do início do plano".
Link de Consentimento: Na resposta de sucesso da criação da assinatura, capture o parâmetro pix_automatic_consent_url.
⚠️ Atenção: O pagador deve ser redirecionado imediatamente, pois o link expira em 60 minutos.
5. Gestão de Webhooks
A integração DEVE ser orientada a eventos. Configure o endpoint de webhooks no painel Vindi e implemente os handlers abaixo:
Tratamento de Respostas
Status Autorizado: Libere o produto/serviço. Pagamentos futuros serão notificados via webhook (Fatura Paga ou Cobrança Rejeitada).
Status Rejeitado/Expirado: Assinatura não ativada. Acione a contingência: peça nova tentativa ou sugira pagamento por cartão de crédito.
6. Fluxo de Exceções
Link Expirado (60 minutos)
Se o cliente não completar a autorização no prazo de 60 minutos:
A assinatura permanece com status Aguardando Consentimento;
O merchant deve gerar e reenviar um novo link de consentimento ao cliente;
Na Página de Pagamento V2, a fatura é cancelada automaticamente para evitar inconsistências;
O link de consentimento fica disponível nos detalhes da assinatura no painel Vindi.
Saldo Insuficiente / Cobrança Rejeitada
Se o débito falhar no dia do vencimento:
A Vindi envia webhook charge_updated com status rejected e motivo saldo_insuficiente;
O consentimento bancário permanece ativo para os ciclos futuros;
O merchant pode alterar o método de pagamento daquela fatura específica (Cartão de Crédito ou Pix avulso).
📝 NOTA: A Vindi não realiza retentativas automáticas para Pix Automático. Qualquer nova tentativa de cobrança deve ser iniciada manualmente via troca de método de pagamento na fatura.
Revogação pelo Cliente
Se o cliente cancelar o consentimento diretamente no app do banco:
A Vindi recebe um callback e dispara o webhook consent_revoked;
Cobranças futuras ficam bloqueadas automaticamente;
O merchant deve oferecer um método de pagamento alternativo ao cliente.
7. Troubleshooting
Para abertura de tickets de suporte técnico:
Problemas de experiência (cliente não consegue abrir o banco): anexar vídeo ou print da tela;
Cobranças rejeitadas: informar o ID de Iniciação e o ID de Consentimento retornados pela API.