Se não for direcionado automaticamente, clique aqui.
Assinaturas Docs
Login

Apresentação

O Moip Assinaturas é a solução do Moip para o gerenciamento e cobrança de mensalidades, assinaturas e pagamentos recorrentes. Este produto permite que você faça cobranças de forma automática, no valor e intervalo que escolher por meio da criação de planos que serão oferecidos aos seus clientes.

Terminologia

Conta Moip O seu cadastro no Moip para recebimento dos pagamentos da assinatura, configuração e também para realizar os saques dos valores recebidos.
Aplicação Site, plataforma ou sistema que está integrado ao Moip Assinaturas usando as APIs
Vendedor Responsável pela venda das assinaturas e pela aplicação. Ele possui uma conta Moip de negócios para receber o pagamento das assinaturas.
Cliente O comprador do vendedor. Ele não possui um relacionamento direto com o Moip Assinaturas.
Plano O plano é semelhante a um produto para o modelo de assinaturas. Por meio da criação de um plano é possível oferecer a contratação de uma assinatura aos clientes.
Assinatura O contrato realizado entre um cliente e um vendedor de acordo com o plano escolhido.
Fatura Conjunto de itens (débitos e créditos) que compõe a cobrança que será feita de acordo com as regras configuradas no plano contratado.
Pagamento Pagamento criado automaticamente pelo Moip Assinaturas, a fim de cobrar uma fatura.
Evento Ações e alterações realizadas em algum elemento da sua Conta Moip, como plano, cliente, assinatura e cobrança. Os eventos podem ser tratados pela sua Aplicação por meio dos Webhooks configurados.
Sandbox Ambiente de testes do Moip Assinaturas. Quando você estiver usando o Sandbox, não serão geradas cobranças reais. Ele servirá para você iniciar sua integração e testar as reações das nossas APIs com a sua aplicação. Após homologação, você poderá ter acesso ao ambiente de Produção e processar pagamento reais.
Produção Ambiente de operação do Moip Assinaturas. Quando você estiver usando o ambiente do Produção, poderá gerar planos, assinaturas e pagamentos com cobranças reais.

Fluxo básico (Assinaturas versão 1.0)

A ilustração acima representa o processo básico de contratação de uma assinatura por um cliente.

Abaixo, um detalhamento das principais etapas do ciclo de vida de um cliente.

1. Contratação de um plano

O cliente pode contratar um plano previamente criado pelo vendedor das seguintes maneiras: pelo próprio site do vendedor, caso ele utilize o moip-assinaturas.js para criar sua página de contratação; utilizando a página de contratação do Moip Assinaturas; solicitando ao vendedor por telefone ou email (nesse caso o vendedor deve criar a assinatura pela área logada).

  • É importante ressaltar que o cliente não precisa ter cadastro no Moip. O processo de contratação pode ser transparente para ele caso o vendedor utilize o JavaScript ou nossas APIs.
  • É de responsabilidade do vendedor notificar ao assinante a respeito de todos os detalhes do plano contratado e também avisá-lo que o pagamento será processado pelo Moip.

2. Cobrança de uma assinatura

  • A primeira cobrança é realizada no momento de criação da assinatura e as próximas serão de acordo com o intervalo determinado pelo plano.
  • Nesta primeira versão, o Moip Assinaturas permite realizar as cobranças recorrentes em cartões de crédito Mastercard e Visa.

3. Mudança de um plano (upgrade/downgrade)

O plano de uma assinatura pode ser alterado a qualquer momento pelo vendedor, por meio da área logada ou da API. Na versão atual do Moip Assinaturas, essas alterações vão ser refletidas na próxima cobrança, sem pró-rata (ou seja, a próxima cobrança vai ser o valor inteiro do novo plano da assinatura, independentemente da data da alteração).

  • É responsabilidade do vendedor realizar a solicitação do assinante para a alteração do plano de uma assinatura e comunicá-lo quando essa alteração for realizada.

4. Faturas não pagas

Caso uma fatura não seja paga (o pagamento não ser realizado por qualquer motivo), o vendedor será notificado por um webhook. O vendedor deve realizar ações que julgar necessárias diretamente com o seu cliente para reaver a cobrança cancelada ou reembolsada. Caso deseje, o vendedor pode suspender a assinatura do comprador inadimplente pela API ou pela área logada.

Caso um pagamento seja cancelado, é possível a substituição do cartão de crédito, para concluir o pagamento da fatura. Esse update é possível tanto via API de Billing_info, quanto através do assinaturas.min.js e da interface do Moip Assinaturas.

5. Retentativas de cobrança

O vendedor tem a opção de configurar retentativas de cobranças paras caso onde a Assinatura esteja com status "Atrasada". As retentativas pode ser automáticas (executadas conforme configurado pelo vendedor), ou manuais, mediante ação do lojista ou do assinante (utilizando a interface ou as APIs de retentativa).

6. Suspensão de uma assinatura

O cliente pode suspender a assinatura diretamente pela plataforma do vendedor (utilizando as APIs - recomendado); por uma solicitação (email, telefone etc.) ao vendedor que deve realizá-la pela área logada; ou por uma solicitação ao Moip. Caso o cliente contate o Moip para realizar esta ação, o Moip irá suspender a assinatura e comunicar ao vendedor.

  • É de responsabilidade do vendedor comunicar ao cliente sobre o cancelamento da assinatura.
  • Caso o assinante solicite o cancelamento, cabe ao vendedor atender esta solicitação o mais rápido possível.
  • A suspensão irá ter efeito nas próximas cobranças, sem pró-rata. A mesma assinatura pode ser reativada depois pelo vendedor.

APIs Moip Assinaturas

O Moip Assinaturas é baseado em um conjunto de APIs que permitem o total controle e integração das ferramentas, de acordo com as suas necessidades.

APIs Descrição
Planos O plano é semelhante a um produto para o modelo de assinaturas. Um plano contém as configurações que uma assinatura vai seguir, como valor e intervalo de cobrança. Crie os planos que deseja oferecer para os seus clientes assinarem.
Clientes Para a criação de uma assinatura, além do plano, é necessário possuir todas as informações do assinante para poder realizar as cobranças e gerenciar o relacionamento com ele. No modelo de assinaturas, o vínculo com o cliente é mais forte do que no e-commerce tradicional, por isso é importante conhecê-lo bem e ter seus dados sempre atualizados.
Assinaturas A assinatura é o vínculo entre um cliente e um plano. Ela determina o contrato que será seguido para a realização das cobranças recorrentes.
Via API, é possível criar um cliente junto da assinatura, na interface é necessária a criação prévia do Cliente.
Faturas A assinatura vai gerar a primeira fatura no momento da contratação de um plano. Depois, periodicamente novas faturas serão geradas de acordo com as configurações do plano contratado. Para consultar as faturas geradas para uma determinada assinatura e seus detalhes, utilize a API de faturas.
Pagamentos Uma fatura pode ser paga utilizando os meios de pagamento de preferência do assinante. Para cada fatura, é gerado um pagamento.
Retentativas Você poderá configurar ou executar retentativas de cobranças para casos onde o pagamento de uma fatura tenha sido cancelado. Para isso, nós oferecemos duas APIs de retentativas, uma delas permite que você gere um novo pagamento imediatamente, cobrando a fatura em atraso, a outra permite configurar retentativas automáticas, que serão executadas pelo Moip Assinaturas.
Preferências A API de preferências pode ser utilizada para configurar as preferências de notificação da loja. Com ela você pode determinar por exemplo, se deseja que o Moip Assinaturas notifique a loja e o assinantes por e-mail, sobre novas cobranças e alterações nas assinaturas. Além disso, você também pode utilizar essa API para configurar a URL de notificação para onde enviaremos os Webhooks.
moipassinaturas.js O JavaScript do Assinaturas permite o desenvolvimento de um checkout para a contratação de assinaturas, enviando os dados sensíveis de pagamento (cartão de crédito) direto para o servidor do Moip, reduzindo o escopo PCI do sistema do vendedor.
Webhooks O seu sistema pode ser notificado das alterações de status de uma cobrança por um POST de um evento enviado pelo Moip Assinaturas.

Veja a documentação completa da APIs.

Passo-a-passo comece a usar o Assinaturas

  1. Crie uma conta Moip para vendedores.
    - É importante verificar a sua conta para ela não ter limitações.
  2. Acesse o menu Ferramentas e depois clique no link Moip Assinaturas
    - Se preferir, clique aqui.
  3. Clique no botão Habilitar Acesso e pronto. Você já pode utilizar o Moip Assinaturas e suas APIs de Sandbox.

Após habilitar sua conta, você terá acesso as APIs de Sandbox do Moip Assinaturas. Para passar a utilizar as APIs de Produção, você terá que passar pelo processo de homologação de integração. Para dar início a esse processo, basta clicar no Botão Produção na área logada do Moip Assinaturas, na página seguinte, preencher o formulário de homologação.

Changelog

30/06/2014
  • Inclusão do hold_setup_fee nas apis e webhooks de planos.

28/10/2013
  • Correção da página de webhooks na documentação no evento subscription.canceled. Link.

03/10/2013
  • Inclusão da função Trial nos Planos.

08/08/2013
01/08/2013
  • Lançamento do Moip Assinaturas no mercado. \o/

12/06/2013
11/06/2013
08/04/2013
25/03/2013
22/03/2013
15/03/2013
  • Nova documentação online (esta mesmo!)
  • URIs para ativação e inativação de planos foram atualizadas.

24/01/2013
  • Novos webhooks de planos, clientes e assiaturas.
  • URIs para ativação e inativação de planos foram atualizadas.

04/01/2013
10/12/2012
21/11/2012