[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 para cobrar a primeira parcela no exato momento da autorização.
Como fazer: Envie a data atual no start_at ou omita o campo.
Payload de exemplo:
JSON{
"payment_method_code": "pix_automatic",
"billing_trigger_type": "beginning_of_period",
"start_at": "2026-04-08"
}
Cenário B: Agendamento Futuro
O cliente autoriza hoje, mas o primeiro pagamento ocorrerá em uma data posterior.
Como fazer: Envie uma data futura no start_at. O sistema registra a autorização agora e agenda a cobrança automaticamente.
Payload de exemplo:
JSON{
"payment_method_code": "pix_automatic",
"billing_trigger_type": "beginning_of_period",
"start_at": "2026-05-15"
}
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 5 minutos.
5. Gestão via Webhooks (Assíncrono)
Como a autorização ocorre no app do banco do cliente, a integração não deve realizar polling (consultas repetitivas). Utilize os Webhooks para monitorar os status:
Consentimento criado: Retorna o link inicial.
Aguardando autorização: Cliente acessou o link, mas ainda não confirmou no banco.
Consentimento autorizado: Sucesso. A assinatura foi ativada e as faturas serão geradas.
Consentimento expirado: O prazo de 5 minutos venceu sem autorização.
Consentimento rejeitado: O cliente negou explicitamente a autorização.
Consentimento cancelado: O cliente revogou uma autorização que já estava ativa.
Tratamento de Respostas
Status Autorizado: Siga com o fluxo de entrega do produto/serviço. Os pagamentos subsequentes serão notificados pelos webhooks padrão de Fatura Paga ou Cobrança Rejeitada.
Status Rejeitado ou Expirado: A assinatura não será ativada. Recomendamos disparar um fluxo de contingência, como solicitar uma nova tentativa ou oferecer pagamento via Cartão de Crédito.