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.
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:
{ "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.
Authorization
possui o token de autenticação, que pode ser consultado na seção "Configurações" da área logada do Moip Assinaturas:
Atualmente as notificações contemplam os seguintes eventos:
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.
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.
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" }
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" } }
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.
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" }] } } }
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.
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" } }
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" } }
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" }
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" }
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" } } }
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" } } }
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.
Request Method: POST Authorization: Basic TOKEN:KEY Content-Type: application/json Accept: application/json
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.
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" } } } }
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" } } }
Você pode reenviar uma notificação de payment.created
via API, basta enviar ao Moip
Assinaturas uma requisição conforme mostrado abaixo.
Request Method: POST Authorization: Basic TOKEN:KEY Content-Type: application/json Accept: application/json
O Simulador do Moip Assinaturas permite que você faça testes de envio e retorno de pagamentos no ambiente de testes (Sandbox).
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.
Valor no atributo customer.fullname |
Status do pagamento simulado |
---|---|
Autorizar |
Autorizado |
Cancelar |
Cancelado |
EmAnalise |
Pré-autorizado |
{ "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": { } } }
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.