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

Webhooks

O Moip Assinaturas utiliza webhooks para notificar a sua aplicação em tempo real sobre os eventos que afetam os recursos da sua conta, como clientes, assinaturas, faturas e pagamentos.

URL de notificação

Para começar a receber os eventos por webhooks, você deve primeiro configurar uma URL para qual você deseja que as notificações sejam enviadas. Você pode fazer isso de duas maneiras. A primeira é acessando a área logada do Moip assinaturas, selecionar o menu configurações e cadastrar.

A segunda maneira é por meio de uma API. Para isso você precisa fazer a seguinte requisição:

POST 
{
    "notification": {
        "webhook": {
            "url": "http://exemploldeurl.com.br/assinaturas"
        }
    }
}

Importante: a URL de notificação para assinaturas deve ser configurada no Moip Assinaturas, sendo assim possível configurar uma URL diferente da cadastrada na sua Conta Moip.

Token de notificação

Para garantir que as notificações têm como origem o Moip Assinaturas, verifique no header da requisição se o parâmetro Authorization possui o token de autenticação, que pode ser consultado na seção "Configurações" da área logada do Moip Assinaturas:

Eventos notificados

Atualmente as notificações contemplam os seguintes eventos:

Estrutura da requisição

O formato da requisição HTTP enviada pelo Moip Assinaturas será sempre a mesma, variando apenas o node resource:

Method: POST
Authorization: Token de notificação
Content-Type: application/json
{
   "event": "plan.created", //tipo de evento
   "date": "01/01/2013 00:00:00", //data da notificação
   "env": "sandbox", //ambiente a partir do qual foi enviada a notificação.
   "resource": { //objeto notificado (variável de acordo com o evento)
       ...
   }
}
Importante: o ambiente pode ser sandbox para o ambiente de testes ou prod para produção.

Planos

Para planos, o sistema do assinaturas envia 4 tipos de eventos: created, updated, activated e inactivated. Para created e updated será notificado o objeto completo.

Criado e Atualizado plan.created e plan.updated

A criação e atualização de plano terá notificação do objeto completo, assim, será possível criar um plano em seu sistema com os mesmos atributos criados no Moip Assinaturas.

{
    "event": "plan.created",
    "resource": {
        "amount": 990,
        "max_qty": 1,
        "setup_fee": 500,
        "interval": {
            "unit": "MONTH",
            "length": 1
        },
        "status": "ACTIVE",
        "description": "Descrição do Plano Especial",
        "name": "Plano Especial",
        "billing_cycles": 12,
        "code": "plano01",
        "trial": {
            "enabled": true,
            "days": 30,
            "hold_setup_fee": true
        }
    },
    "env": "sandbox",
    "date": "01/01/2013 00:00:00"
}

Habilitado e Desabilitado plan.activated e plan.inactivated

Nestes dois eventos será notificado apenas o código de identificação da sua aplicação.

{
   "event": "plan.activated", 
   "date": "01/01/2013 00:00:00",
   "env": "sandbox",
   "resource": { 
        "code": "plano01"
   }
}

Cliente

O Moip Assinaturas envia dois tipos de eventos: created e updated.
O node billing_info.credit_cards sempre será enviado, mas vai estar vazio caso o cliente não não possuia informações de cartão de crédito ainda.

Criado e Atualizado customer.created e customer.updated

A criação e atualização do cliente tem notificação do objeto completo, assim, é possível criar ou atualizar um cliente em seu sistema com os mesmos atributos criados no Moip Assinaturas.

{
   "event": "customer.created", 
   "date": "01/01/2013 00:00:00",
   "env": "sandbox",
   "resource": { 
        "code": "cliente01",
        "fullname": "Nome completo do Cliente",
        "cpf": "11111111111",
        "birthdate_day": 11,
        "birthdate_month": 10,
        "birthdate_year": 1986
        "email": "teste@teste.com",
        "phone_area_code": "11",
        "phone_number": "111111111",
        "address": {
            "street": "Rua Teste",
            "number": "1",
            "complement": "apto 1",
            "district": "Teste",
            "zipcode": "11111111",
            "city": "São Paulo",
            "state": "São Paulo",
            "country": "BRA"
        },
        "billing_info": { // estará vazio se o cliente não possuir dados de cobrança.
            "credit_cards": [{
                    "vault": "teste-teste00-1teste-t35t3-135879",
                    "holder_name": "Nome do portador no cartao",
                    "first_six_digits": "411111",
                    "last_four_digits": "1111"
                    "expiration_month": "09",
                    "expiration_year": "16",
                    "brand": "VISA"
                }]
        }
   }
}

Assinatura

O Moip Assinaturas envia cinco tipos de eventos: created, updated, suspended, activated e canceled.

No processo de criação de uma assinatura, o sistema do Moip cria um pagamento payment, uma fatura invoice e por fim, a própria assinatura subscription. A sua aplicação deve receber webhook para cada um desses eventos nesta ordem. Caso seja apenas uma atualização de uma assinaturas, você deve esperar receber apenas a notificação da assinaturas.

Criada subscription.created

A criação da assinatura tem a notificação do objeto completo. Antes da notificação da assinatura, são enviadas as notificações de fatura e pagamento.

{
    "event": "subscription.created",
    "resource": {
        "amount": 990,
        "creation_date": {
            "month": 01,
            "year": 2013,
            "day": 01
        },
        "plan": {
            "code": "plano01"
        },
        "status": "ACTIVE",
        "expiration_date": {
            "month": 06,
            "year": 2013,
            "day": 01
        },
        "next_invoice_date": {
            "month": 02,
            "year": 2013,
            "day": 01
        },
        "code": "assinatura01",
        "customer": {
            "code": "cliente01"
        }
    },
    "env": "sandbox",
    "date": "01/01/2013 00:00:00"
}
}

Atualizada subscription.updated

A atualização de assinatura tem notificação do objeto completo.

{
    "event": "subscription.updated",
    "resource": {
        "amount": 15000,
        "creation_date": {
            "month": 01,
            "year": 2013,
            "day": 01
        },
        "plan": {
            "code": "plano01"
        },
        "status": "ACTIVE",
        "expiration_date": {
            "month": 06,
            "year": 2013,
            "day": 01
        },
        "next_invoice_date": {
            "month": 02,
            "year": 2013,
            "day": 01
        },
        "code": "assinatura01",
        "customer": {
            "code": "cliente01"
        }
    },
    "env": "sandbox",
    "date": "01/01/2013 00:00:00"
}
}

Suspensa e Ativa subscription.suspended e subscription.activated

Para suspended e activated, é notificado apenas o código de identificação da sua aplicação.

{
    "event": "subscription.suspended",
    "resource": {
        "code": "assinatura01"
    },
    "env": "prod",
    "date": "01/01/2013 00:00:00"
}

Cancelada subscription.canceled

Esse webhook notifica o cancelamento de uma assinatura.

{
    "event": "subscription.canceled",
    "resource": {
        "code": "assinatura01"
    },
    "env": "sandbox",
    "date": "01/01/2013 00:00:00"
}

Fatura

Criada invoice.created

{
   "event": "invoice.created",
   "date": "01/01/2013 00:00:00",
   "env": "sandbox",
   "resource": {
       "id": 13, //ID da fatura
       "subscription_code": "assinatura01",
       "amount": 101,
       "occurrence": 1,
       "status": {
           "code": 1,
           "description": "Em aberto"
       }
   }
}

Atualizada invoice.status_updated

{
   "event": "invoice.status_updated",
   "date": "01/01/2013 00:00:00",
   "env": "sandbox",
   "resource": {
       "id": 13, //ID da fatura
       "status": { //novo status da fatura
           "code": 2,
           "description": "Aguardando confirmação"
       }
   }
}

Reenvio de notificação de fatura

Você pode solicitar o reenvio de uma notificação de invoice.created via API. Para isso, basta enviar ao Moip Assinaturas uma requisição conforme mostrado abaixo.

Requisição

POST 
Request Method: POST
Authorization: Basic TOKEN:KEY
Content-Type: application/json
Accept: application/json

Pagamento

Sempre que um pagamento for gerado, o Moip Assinaturas envia o objeto de Pagamento completo. Se o pagamento ter o status atualizado, é enviado apenas o novo status.

Criado payment.created

{
   "event": "payment.created",
   "date": "01/01/2013 00:00:00",
   "env": "sandbox",
   "resource": {
       "id": 6, //ID do pagamento
       "invoice_id": 13,
       "moip_id": 14456223,
       "subscription_code": "assinatura01",
       "amount": 101,
       "status": {
           "code": 2,
           "description": "Iniciado"
       },
       "payment_method": {
           "code": 1,
           "description": "Cartão de Crédito",
           "credit_card": { //enviado apenas se foi pago com cartão de crédito
               "brand": "VISA",
               "holder_name": "Fulano Testador",
               "first_six_digits": "411111",
               "last_four_digits": "1111",
               "vault": "cc7719e7-9543-4380-bdfe-c14d0e3b8ec9"
           }
       }
   }
}

Status atualizado payment.status_updated

{
   "event": "payment.status_updated",
   "date": "01/01/2013 00:00:00",
   "env": "sandbox",
   "resource": {
       "id": 6, //identificador do pagamento
       "status": { //novo status do pagamento
           "code": 6,
           "description": "Em análise"
       }
   }
}

Reenvio de notificação de pagamento

Você pode reenviar uma notificação de payment.created via API, basta enviar ao Moip Assinaturas uma requisição conforme mostrado abaixo.

Requisição

POST 
Request Method: POST
Authorization: Basic TOKEN:KEY
Content-Type: application/json
Accept: application/json

Simulando status de pagamento

O Simulador do Moip Assinaturas permite que você faça testes de envio e retorno de pagamentos no ambiente de testes (Sandbox).

Como usar o simulador

Na criação da assinatura, envie no atributo customer.fullname o valor relacionado ao status que você deseja receber na simulação da cobrança.

Status de pagamento que podem ser simulados
Valor no atributo customer.fullname Status do pagamento simulado
Autorizar Autorizado
Cancelar Cancelado
EmAnalise Pré-autorizado
Simulando pela API exemplo de requisição
POST 
{
  "code": "assinatura01",
  "plan": {
      "code": "plano01"
  },
  "customer": {
      "code": "cliente01",
      "email": "fulano@teste.com.br",
      "fullname": " Autorizar",  //altere o valor para utilizar o simulador
      "cpf": "22222222222",
      "phone_number": "55223366",
      "phone_area_code": "11",
      "birthdate_day": "26",
      "birthdate_month": "04",
      "birthdate_year": "1986",
      "address": {
      },
      "billing_info": {
      }
  }
}
Simulando pela área logada

Para utilizar o simulador a partir da área logada do Moip Assinaturas, cadastre um cliente com o nome de acordo com o status que deseja testar e crie uma assinatura para ele.