Pix Automático

Disponível apenas em Sandbox

O Pix Automático está disponível somente no ambiente Sandbox. Não há suporte em produção no momento.

O Pix Automático permite que o seu cliente autorize, uma única vez, cobranças recorrentes debitadas diretamente da conta dele, sem precisar aprovar cada pagamento. É a modalidade indicada para mensalidades, assinaturas, parcelas de crédito e contas de consumo.

Diferente do débito automático tradicional, não é necessário convênio com cada banco. E diferente do cartão salvo, a cobrança não falha porque o cartão expirou, foi trocado ou bloqueado.

Na Marlim você não precisa construir telas de autorização. Basta criar um link de autorização com as regras do contrato (periodicidade, valores e vigência) e enviar o cliente para ele. A jornada conduz o cliente até o banco dele, onde ele aprova o Pix Automático, e devolve o resultado para a sua aplicação.

Dica

O link de autorização é persistente: se o cliente abandonar a jornada (queda de conexão, banco indisponível, desistência momentânea), ele pode voltar ao mesmo link e concluir a autorização até que ela seja finalizada ou o link expire.

Como funciona

Etapa	O que acontece
1	O cliente autoriza uma vez. No app do banco, ele aprova a recorrência com valor fixo ou variável, periodicidade e vigência.
2	Você agenda as cobranças. Cada cobrança é agendada de 2 a 10 dias antes da data de liquidação, dentro das regras aprovadas pelo cliente.
3	O valor é liquidado via Pix. Na data agendada o débito é executado. Se falhar, você pode solicitar até 3 novas tentativas em até 7 dias.

Regras da autorização

Regra	Descrição
Valor	Valor fixo (ex.: mensalidade) ou variável dentro de uma faixa (ex.: fatura de consumo do mês).
Periodicidade	Semanal, mensal, trimestral, semestral ou anual.
Limites	Valor mínimo por cobrança definido por você e valor máximo por cobrança, que o cliente pode reduzir no banco dele.
Vigência	Data de início e de fim da autorização, ou prazo indeterminado.
Retentativa	O cliente aceita ou não novas tentativas em caso de falha. Veja as Regras de Retentativa.
Primeira cobrança	Opcional. A primeira cobrança pode ser liquidada junto com a autorização.

Conceitos

Conceito	Descrição
Link de autorização	URL gerada pela Marlim onde o cliente revisa e aprova o Pix Automático. Possui status próprio e data de expiração.
Autorização	Consentimento recorrente aprovado pelo cliente no banco dele. Define recebedor, periodicidade e limites de valor. É ela que permite agendar cobranças.
Cobrança	Cada débito agendado dentro de uma autorização ativa. Possui data de liquidação, valor e status próprios.
Retentativa	Nova tentativa de liquidar uma cobrança que falhou, dentro das janelas permitidas pelo arranjo Pix.

Fluxo da integração

Etapa	Quem executa	O que acontece
1	Sua aplicação	Cria o link de autorização com o Criar Link.
2	Sua aplicação	Envia o cliente para a authorization_url retornada (navegador ou WebView).
3	Cliente	Escolhe o banco e aprova o Pix Automático no app do banco.
4	Marlim	Redireciona o cliente para a sua redirect_url e notifica o resultado no seu webhook.
5	Sua aplicação	Com a autorização em authorized, agenda as cobranças com o Agendar Cobrança.
6	Marlim	Envia cada cobrança para liquidação na data agendada e notifica cada mudança de status.

Atenção

Crie links e agende cobranças sempre a partir do seu servidor. Nunca exponha a sua api_key no navegador ou no aplicativo do cliente.

Modalidade "Sua Interface"

Se você precisa controlar toda a experiência (escolha do banco, telas e redirecionamento) dentro do seu site ou app, a integração sem o link de autorização está disponível sob consulta. Fale com o nosso time de Desenvolvimento.

Casos de uso

Segmento	Exemplo
Educação	Mensalidades escolares e de cursos.
Assinaturas e SaaS	Planos mensais ou anuais de conteúdo digital e software.
Crédito	Parcelas semanais ou mensais de empréstimos e financiamentos.
Contas de consumo	Água, luz, gás, telefonia e internet, com valor variável a cada ciclo.
Saúde	Planos e mensalidades de clínicas e operadoras.

Boas práticas

Prática	Como aplicar
Combine webhook e consulta	Use os webhooks como fonte principal de atualização e as consultas como contingência.
Guarde os IDs da Marlim	Salve o link_id, o authorization_id e cada charge_id junto do seu registro. As consultas e ações são feitas por esses IDs.
Envie o item_id	Informe o identificador do seu sistema no link e nas cobranças. Ele volta nas consultas e nos webhooks e facilita a conciliação e o suporte.
Deixe claro que o débito é automático	Informe ao cliente a periodicidade, o valor ou a faixa de valor e como cancelar.
Confira a autorização	Agende ou retente uma cobrança somente com a autorização em authorized.
Respeite os prazos	Siga os prazos de agendamento e de retentativa. Pedidos fora do prazo são rejeitados.
Trate as rejeições pelo código	Use o code da rejeição, nunca o texto de detail, que é livre e varia por banco.