Pix Agendado
O Pix Agendado está disponível somente no ambiente Sandbox. Não há suporte em produção no momento.
O Pix Agendado não está disponível para todas as contas e depende de habilitação prévia pela Marlim. Para verificar a elegibilidade da sua conta, entre em contato com o nosso time comercial.
O Pix Agendado permite que o seu cliente aprove, uma única vez, um ou mais pagamentos Pix com datas futuras. Depois da aprovação no banco, cada pagamento é liquidado automaticamente na data agendada, sem nenhuma nova ação do cliente.
É a modalidade indicada quando o valor e as datas já são conhecidos no momento da compra, como o parcelamento de um curso, o pagamento de uma reserva na data da viagem ou um plano com número fixo de pagamentos.
Na Marlim você não precisa construir telas de aprovação. Basta criar um link de pagamento com o valor e o agendamento e enviar o cliente para ele. A jornada conduz o cliente até o banco dele, onde ele aprova os pagamentos, e devolve o resultado para a sua aplicação.
Pix Agendado ou Pix Automático
| Pix Agendado | Pix Automático | |
|---|---|---|
| Valor | Fixo, o mesmo em todas as datas. | Fixo ou variável dentro de uma faixa. |
| Datas | Todas definidas na criação e aprovadas de uma vez. | Você agenda cada cobrança ao longo da vigência. |
| Quantidade | Número fixo de pagamentos. | Sem número fixo, enquanto a autorização estiver ativa. |
| Indicado para | Parcelamentos e pagamentos com datas conhecidas. | Mensalidades, assinaturas e contas de consumo. |
Se o valor varia a cada ciclo ou a recorrência não tem fim definido, use o Pix Automático.
Como funciona
| Etapa | O que acontece |
|---|---|
| 1 | Você cria o link de pagamento. Informa o valor, o tipo de agendamento e as datas. |
| 2 | O cliente aprova uma vez. No app do banco, ele aprova todos os pagamentos do agendamento. |
| 3 | Cada pagamento é liquidado na data. O débito acontece na data agendada e o valor é creditado na conta recebedora. |
Regras do agendamento
| Regra | Descrição |
|---|---|
| Tipos | Pagamento único em data futura, diário, semanal, mensal ou em datas personalizadas. Veja o objeto schedule. |
| Valor | O mesmo valor para todas as datas do agendamento. |
| Datas | A partir do dia seguinte à criação e até 2 anos à frente. |
| Quantidade | De 2 a 60 pagamentos nos agendamentos diário, semanal e personalizado, e de 2 a 24 no mensal. O pagamento único pode ser agendado para até 365 dias à frente. |
| Cancelamento | Cada pagamento agendado pode ser cancelado até as 23:59 do dia anterior à data, pelo cliente no banco dele ou por você pelo Cancelar Pagamento. |
| Falta de saldo | Se a conta do cliente não tiver saldo na data, o banco dele faz uma nova tentativa no mesmo dia, no fim da tarde ou à noite, conforme a regra de cada banco. Não há retentativa pela API. |
Conceitos
| Conceito | Descrição |
|---|---|
| Link de pagamento | URL gerada pela Marlim onde o cliente revisa e aprova os pagamentos agendados. Possui status próprio e data de expiração. |
| Agendamento | Conjunto de datas aprovado pelo cliente, definido pelo objeto schedule. |
| Pagamento | Cada débito do agendamento. Possui data de liquidação e status próprios. |
Fluxo da integração
| Etapa | Quem executa | O que acontece |
|---|---|---|
| 1 | Sua aplicação | Cria o link de pagamento com o Criar Link. |
| 2 | Sua aplicação | Envia o cliente para a payment_url retornada (navegador ou WebView). |
| 3 | Cliente | Escolhe o banco e aprova os pagamentos agendados no app do banco. |
| 4 | Marlim | Redireciona o cliente para a sua redirect_url e notifica o resultado no seu webhook. |
| 5 | Marlim | Liquida cada pagamento na data agendada e notifica cada mudança de status. |
| 6 | Sua aplicação | Acompanha os pagamentos pelos webhooks ou pelo Listar Pagamentos. |
Crie links e cancele pagamentos sempre a partir do seu servidor. Nunca exponha a sua api_key no navegador ou no aplicativo do cliente.
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 pagamento está disponível sob consulta. Fale com o nosso time de Desenvolvimento.
Casos de uso
| Segmento | Exemplo |
|---|---|
| Educação | Parcelamento de cursos, materiais e matrículas. |
| Turismo | Reserva paga em parcelas até a data da viagem. |
| Varejo | Compras parceladas via Pix, sem cartão de crédito. |
| Serviços | Planos com número fixo de pagamentos, como tratamentos e consultorias. |
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 e cada payment_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. Ele volta nas consultas e nos webhooks e facilita a conciliação e o suporte. |
| Mostre o agendamento antes | Informe ao cliente o valor, a quantidade e as datas dos pagamentos antes de enviar o cliente ao banco. |
| Trate o cancelamento pelo cliente | O cliente pode cancelar pagamentos no banco dele. Acompanhe o status canceled e ofereça outra forma de pagamento. |
| Trate as rejeições pelo código | Use o code do erro, nunca o texto de detail, que é livre e varia por banco. |