Pular para o conteúdo principal

Pix Agendado

Disponível apenas em Sandbox

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 AgendadoPix Automático
ValorFixo, o mesmo em todas as datas.Fixo ou variável dentro de uma faixa.
DatasTodas definidas na criação e aprovadas de uma vez.Você agenda cada cobrança ao longo da vigência.
QuantidadeNúmero fixo de pagamentos.Sem número fixo, enquanto a autorização estiver ativa.
Indicado paraParcelamentos 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​

EtapaO que acontece
1Você cria o link de pagamento. Informa o valor, o tipo de agendamento e as datas.
2O cliente aprova uma vez. No app do banco, ele aprova todos os pagamentos do agendamento.
3Cada pagamento é liquidado na data. O débito acontece na data agendada e o valor é creditado na conta recebedora.

Regras do agendamento​

RegraDescrição
TiposPagamento único em data futura, diário, semanal, mensal ou em datas personalizadas. Veja o objeto schedule.
ValorO mesmo valor para todas as datas do agendamento.
DatasA partir do dia seguinte à criação e até 2 anos à frente.
QuantidadeDe 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.
CancelamentoCada 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 saldoSe 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​

ConceitoDescrição
Link de pagamentoURL gerada pela Marlim onde o cliente revisa e aprova os pagamentos agendados. Possui status próprio e data de expiração.
AgendamentoConjunto de datas aprovado pelo cliente, definido pelo objeto schedule.
PagamentoCada débito do agendamento. Possui data de liquidação e status próprios.

Fluxo da integração​

EtapaQuem executaO que acontece
1Sua aplicaçãoCria o link de pagamento com o Criar Link.
2Sua aplicaçãoEnvia o cliente para a payment_url retornada (navegador ou WebView).
3ClienteEscolhe o banco e aprova os pagamentos agendados no app do banco.
4MarlimRedireciona o cliente para a sua redirect_url e notifica o resultado no seu webhook.
5MarlimLiquida cada pagamento na data agendada e notifica cada mudança de status.
6Sua aplicaçãoAcompanha os pagamentos pelos webhooks ou pelo Listar Pagamentos.
Atenção

Crie links e cancele pagamentos 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 pagamento está disponível sob consulta. Fale com o nosso time de Desenvolvimento.

Casos de uso​

SegmentoExemplo
EducaçãoParcelamento de cursos, materiais e matrículas.
TurismoReserva paga em parcelas até a data da viagem.
VarejoCompras parceladas via Pix, sem cartão de crédito.
ServiçosPlanos com número fixo de pagamentos, como tratamentos e consultorias.

Boas práticas​

PráticaComo aplicar
Combine webhook e consultaUse os webhooks como fonte principal de atualização e as consultas como contingência.
Guarde os IDs da MarlimSalve 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_idInforme 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 antesInforme ao cliente o valor, a quantidade e as datas dos pagamentos antes de enviar o cliente ao banco.
Trate o cancelamento pelo clienteO cliente pode cancelar pagamentos no banco dele. Acompanhe o status canceled e ofereça outra forma de pagamento.
Trate as rejeições pelo códigoUse o code do erro, nunca o texto de detail, que é livre e varia por banco.