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

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.

Criar um plano

Requisição exemplo completo

POST 
Request Method: POST 
Authorization: Basic TOKEN:KEY
Content-Type: application/json
Accept: application/json
{
    "code": "plano01",
    "name": "Plano Especial",
    "description": "Descrição do Plano Especial",
    "amount": 990, //em centavos
    "setup_fee": 500, // em centavos
    "max_qty": 1,
    "status": "ACTIVE",
    "interval": {
        "length": 1,
        "unit": "MONTH"
    },
    "billing_cycles": 12,
    "trial": {
        "days": 30,
        "enabled": true,
        "hold_setup_fee": true
    }
}

Atributos

Atributo Formato esperado Descrição Obrigatoriadade
identificação
code "plano01" identificador do plano na sua aplicação. Até 65 caracteres. obrigatório
name "Plano Especial" nome do plano na sua aplicação. Até 65 caracteres. obrigatório
description "plano com desconto para clientes novos" descrição do plano na sua aplicação. Até 255 caracteres.
valores
amount 990 valor do plano a ser cobrado em centavos de Real. obrigatório
setup_fee 500 taxa de contratação a ser cobrada na assinatura em centavos de Real.
intervalo
interval node do intervalo do plano, contendo unit e length condicional
├── unit MONTH a unidade de medida do intervalo de cobrança, o default é MONTH. Opções: DAY, MONTH, YEAR condicional
└── length 1 a duração do intervalo de cobrança, default é 1 condicional
billing_cycles 12 quantidade de ciclos (faturas) que a assinatura terá até expirar (se não informar, não haverá expiração).
trial
trial node do trial, contendo days e enabled
├── days 30 número de dias de trial do plano.
├── enabled TRUE determina se o trial está ou não habilitado. Opções: TRUE ou FALSE, default é FALSE.
└──hold_setup_fee TRUE determina se o setup_fee será cobrado antes ou após o período de trial. Opções: TRUE (após) ou FALSE (antes). Default é TRUE.
configurações
status ACTIVE status do plano. Pode ser ACTIVE ou INACTIVE. O padrão é ACTIVE.
max_qty 12 quantidade máxima de assinaturas do plano (não há limite se não informar)

Resposta

Sucesso
Status: 201 CREATED
URI: https://sandbox.moip.com.br/assinaturas/v1/plans/{code}
{
    message: "Plano criado com sucesso"
}
Erro
Status: 400 BAD REQUEST
{
    "message": "Erro na requisição",
    "errors": [
        {
            "code": "MA1",
            "description": "Código já utilizado. Informe outro código."
        }
    ]
}

Listar todos os planos

Requisição

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

Resposta

Sucesso
Status: 200 OK
{
    "plans": [
        {
            "code": "plano01",
            "name": "Plano Especial",
            "description": "Descrição do Plano Especial",
            "amount": 990, // em centavos
            "setup_fee": 500, // em centavos
            "max_qty": 1,
            "interval": {
                "length": 1,
                "unit": "MONTH"
            },
            "billing_cycles": 12,
            "trial": {
                "days": 30,
                "enabled": true,
                "hold_setup_fee": true
            }
        }
    ]
}

Consultar detalhes de um plano

Requisição

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

Resposta

Sucesso
Status: 200 OK
{
    "code": "plano01",
    "name": "Plano Especial",
    "description": "Descrição do Plano Especial",
    "amount": 990, // em centavos
    "setup_fee": 500, // em centavos
    "max_qty": 1,
    "interval": {
        "length": 1,
        "unit": "MONTH"
    },
    "billing_cycles": 12,
    "trial": {
        "days": 30,
        "enabled": true,
        "hold_setup_fee": true
    }
}

Ativar ou desativar um plano

Requisição

Ativar
PUT

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

Alterar um plano

É possível alterar os dados de um plano criado por meio da API e pela área logada. Contudo, se o plano já possuir assinaturas, algumas informações sensíveis (como valor e intervalo) não poderão ser alteradas para não afetar as assinaturas criadas.

Requisição

PUT 
Request Method: PUT
Authorization: Basic TOKEN:KEY
Content-Type: application/json
Accept: application/json
{
    "code": "plano01",
    "name": "Plano Especial",
    "description": "Descrição do Plano Especial",
    "amount": 990, //em centavos
    "setup_fee": 500, // em centavos
    "max_qty": 1,
    "interval": {
        "length": 1,
        "unit": "MONTH"
    },
    "billing_cycles": 12,
    "trial": {
        "days": 30,
        "enabled": true,
        "hold_setup_fee": true
    }
}
Atributos que podem ser alterados
Atributo alteração
name sempre
description sempre
amount Apenas se não houver assinaturas
setup_fee sempre
interval Apenas se não houver assinaturas
├── unit Apenas se não houver assinaturas
└── length Apenas se não houver assinaturas
billing_cycles Apenas se não houver assinaturas
trial sempre
├── days sempre
└── enabled sempre
status sempre
max_qtd sempre

Clientes e dados de pagamento

Para criar uma assinatura, você precisa cadastrar um cliente com os dados de pagamento. Isso pode ser feito por meio desta API ou no ato de criação da assinatura. É altamente recomendado a utilização do moip-assinaturas.js para reduzir o escopo PCI da sua aplicação.

Criar um cliente

Requisição

POST

Se new_valt=true, o envio do node "credit_card"{} é obrigatório. Utilize isto para criar um cliente com dados de cartão e gerar um cofre para guardar os dados de pagamento com segurança no Moip. 

Request Method: POST
Authorization: Basic TOKEN:KEY
Content-Type: application/json
Accept: application/json
{
    "code": "cliente01",
    "email": "nome@exemplo.com.br",
    "fullname": "Nome Sobrenome",
    "cpf": "22222222222",
    "phone_area_code": "11",
    "phone_number": "934343434",
    "birthdate_day": "26",
    "birthdate_month": "04",
    "birthdate_year": "1980",
    "address": {
        "street": "Rua Nome da Rua",
        "number": "100",
        "complement": "Casa",
        "district": "Nome do Bairro",
        "city": "São Paulo",
        "state": "SP",
        "country": "BRA",
        "zipcode": "05015010"
    },
    "billing_info": {
        "credit_card": {
            "holder_name": "Nome Completo",
            "number": "4111111111111111",
            "expiration_month": "04",
            "expiration_year": "15"
        }
    }
}

Atributos

Atributo Formato esperado Descrição Obrigatoriedade
code "aa001" identificador do cliente na sua aplicação. Até 65 caracteres. obrigatório
fullname "Nome Sobrenome" nome completo do cliente. Até 150 caracteres. obrigatório
email "nome@exemplo.com.br" email do cliente. obrigatório
cpf 16412725297 CPF do cliente. Apenas dígitos numéricos. obrigatório
phone_area_code "11" código de área do telefone do titular (DDD). 2 carateres sem máscara. obrigatório
phone_number "934343434" telefone do titular, 8 ou 9 caracteres sem máscara. obrigatório
birthdate_day "01" dia do nascimento. Válido 1 a 31. obrigatório
birthdate_month "01" mês do nascimento. Válido 1 a 12. obrigatório
birthdate_year "1999" ano do nascimento. 4 dígitos. obrigatório
address node com os atributos do endereço. obrigatório
├── street "Rua dos Valentes" logradouro do endereço. obrigatório
├── state "SP" Estado. obrigatório
├── country "BRA" país. obrigatório
└── zipcode "00000000" CEP do endereço. Sem máscara. obrigatório
billing_info dados de pagamento desse cliente. condicional
├── credit_card dados de cartão de crédito. condicional
│ ├── holder_name "Nome completo" nome do portador. condicional
│ ├── number "4111111111111111" número do cartão de crédito. condicional
│ ├── expiration_month "03" mês de expiração do cartão. condicional
│ ├── expiration_year "16" ano de expiração do cartão. condicional
└─└── vault "e3er4-t1td3-rf4f4f-r4t4" cofre de um cartão de crédito, se já foi cadastrado para este mesmo cliente anteriormente. Caso informe o cofre, os demais dados do cartão não precisam ser informados. condicional

Resposta

Sucesso
Status: 201 CREATED
URI: https://sandbox.moip.com.br/assinaturas/v1/customers/{code}
{
    "message": "Cliente criado com Sucesso"
}
Erro
Status: 400 BAD REQUEST
{
    "message": "Erro na requisição",
    "errors": [
        {
            "code": "MA1",
            "description": "Erro inesperado"
        }
    ]
}

Listar todos os clientes

Requisição

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

Resposta

Sucesso
Status 200: OK
{
    "customers": [
        {
            "code": "cliente01",
            "fullname": "Nome Sobrenome",
            "email": "nome@exemplo.com",
            "cpf": "22222222222",
            "phone_area_code": "11",
            "phone_number": "934343434",
            "birthdate_day": "29",
            "birthdate_month": "04",
            "birthdate_year": "1980"
        }
    ]
}

Consultar detalhes de um cliente

Requisição

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

Resposta

Sucesso
Status 200: OK
{
    "code": "cliente01",
    "fullname": "Nome Sobrenome",
    "email": "nome@exemplo.com",
    "cpf": "22222222222",
    "phone_area_code": "11",
    "phone_number": "934343434",
    "birthdate_day": 29,
    "birthdate_month": 03,
    "birthdate_year": 1980,
    "address": {
        "street": "Rua Nome da Rua",
        "number": "1000",
        "complement": "Apto 4 - bloco A",
        "district": "Bairro",
        "city": "São Paulo",
        "state": "SP",
        "country": "BRA",
        "zipcode": "00000000"
    },
    "billing_info": {
        "credit_cards": [
            {
                "vault": "00b21555-296a-4e70-94cd-3e96fef62e5b",
                "brand": "VISA",
                "first_six_digits": "411111",
                "last_four_digits": "1111",
                "expiration_month": "04",
                "expiration_year": "15",
                "holder_name": "Nome Sobrenome"
            }
        ]
    }
}

Alterar um cliente

Requisição para alterar os dados de um cliente, exceto o seu código. Para alterar os dados de pagamento do cliente, utilize o moip-assinaturas.js.

Requisição

PUT 
Request Method: PUT
Authorization: Basic TOKEN:KEY
Content-Type: application/json
Accept: application/json
{
    "code": "cliente01",
    "email": "nome@exemplo.com.br",
    "fullname": "Nome Sobrenome",
    "cpf": "22222222222",
    "phone_number": "934343434",
    "phone_area_code": "11",
    "birthdate_day": "26",
    "birthdate_month": "04",
    "birthdate_year": "1986",
    "address": {
        "street": "Rua nome da Rua",
        "number": "170",
        "complement": "Casa",
        "district": "Bairro",
        "city": "São Paulo",
        "state": "SP",
        "country": "BRA",
        "zipcode": "00000-000"
    }
}

Atualizar cartão do cliente

Atualize os dados de pagamento de seu cliente.

É possível alterar os dados do pagamento via API, Javascript ou pela área logada do Moip Assinaturas.

Requisição

PUT 
Request Method: PUT
Authorization: Basic TOKEN:KEY
Content-Type: application/json
Accept: application/json
{
        "credit_card": {
            "holder_name": "Novo nome",
            "number": "5555666677778884",
            "expiration_month": "04",
            "expiration_year": "15"
        }
 }
Atenção: ao realizar qualquer processo que envolva dados sensíveis de cartão de crédito em seu ambiente, é altamente recomendado que você siga as normas e boas práticas do PCI Compliance para garantir a segurança de sua aplicação e dos dados de seus clientes.

Assinaturas

Uma assinatura permite a cobrança recorrente de um cliente de forma automática e simples. Para criar uma nova assinatura, basta informar o plano, o cliente da assinatura e um identificador para ela. Se quiser, é possível criar o cliente e seus dados de pagamento junto com a assinatura. Para isso, recomendamos utilizar o moip-assinaturas.js.

Criar Assinaturas

Requisição

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

Exemplo mínimo

Criando uma assinatura com um cliente já cadastrado

{
    "code": "assinatura01",
    "amount": "9990", // em centavos
    "plan" : {
        "code" : "plano01"
    },
    "customer" : {
    "code" : "cliente01"
    }
}

Exemplo completo

Criando uma assinatura com dados de um novo cliente

POST 
{
    "code": "assinatura01",
    "amount": "9990", // em centavos
    "plan": {
        "code": "plano01"
    },
    "customer": {
        "code": "cliente01",
        "email": "nome@exemplo.com.br",
        "fullname": "Nome Sobrenome",
        "cpf": "22222222222",
        "phone_number": "934343434",
        "phone_area_code": "11",
        "birthdate_day": "26",
        "birthdate_month": "04",
        "birthdate_year": "1986",
        "address": {
            "street": "Rua nome da Rua",
            "number": "170",
            "complement": "Casa",
            "district": "Bairro",
            "city": "São Paulo",
            "state": "SP",
            "country": "BRA",
            "zipcode": "00000000"
        },
        "billing_info": {
            "credit_card": {
                "holder_name": "Nome Completo",
                "number": "4111111111111111",
                "expiration_month": "04",
                "expiration_year": "15"
            }
        }
    }
}

Atributos

Atributo Formato esperado Descrição Obrigatoriedade
code "assinatura01" identificador da assinatura na sua aplicação. Até 65 caracteres. obrigatório
amount "9990" valor da assinatura (sobrescreve o valor do plano contratado) atenção: o cliente deve estar ciente e de acordo em ser cobrado um valor diferente do plano escolhido.
plan node de informações do plano que será usado na assinatura obrigatório
└── code "plano01" identificador do plano previamente criado e que será usado na assinatura obrigatório
customer node de informações do cliente que será o assinante obrigatório
└── code "cliente01" identificador do cliente previamente criado e que será usado na assinatura. importante: se o cliente ainda não tiver sido criado, todos os parâmetros do clientes devem ser enviados, consulte a documentação de Clientes. obrigatório

Resposta

O Moip Assinaturas deve responder praticamente em tempo real. Contudo, como a cobrança depende de comunicação com as operadoras de cartões de crédito, em raras exceções pode haver um intervalo maior para resposta. Assim, recomendamos configurar o time-out de requisição da sua aplicação para 40 segundos.

Sucesso

Status: 201 CREATED
URI: https://sandbox.moip.com.br/assinaturas/v1/subscriptions/{code}
{
    "amount": 9990, // em centavos
    "message": "Assinatura criada com sucesso",
    "errors": [],
    "plan": {
        "name": "Plano Especial",
        "code": "plano01"
    },
    "status": "TRIAL",
    "invoice": {
        "amount": 0, // em centavos
        "id": 1000,
        "status": {
            "description": "Pago",
            "code": 3
        }
    },
    "alerts": [],
    "next_invoice_date": {
        "month": 01,
        "year": 2013,
        "day": 31
    },
    "code": "assinatura01",
    "customer": {
        "email": "nome@exemplo.com.br",
        "code": "cliente01",
        "fullname": "Nome e Sobrenome"
    }
}

Erro

Status: 400 BAD REQUEST
{
    "message": "Erro na requisição",
    "errors": [
        {
            "code": "MA92",
            "description": "Código da assinatura já utilizado. Escolha outro código"
        }
    ]
}

Listar todas assinaturas

Requisição

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

Resposta

Sucesso

Status: 200 OK
{
    "subscriptions": [
        {
            "code": "assinatura01",
            "amount": "9990", // em centavos
            "status": "ACTIVE",
            "creation_date": {
                "day": "20",
                "month": "10",
                "year": "2012",
                "hour": "20",
                "minute": "00",
                "second": "00"
            },
            "next_invoice_date": {
                "day": "20",
                "month": "11",
                "year": "2012"
            },
            "expiration_date": {
                "day": "20",
                "month": "10",
                "year": "2013"
            },
            "plan": {
                "name": "Plano Especial",
                "code": "plano01"
            },
            "customer": {
            "code": "cliente01",
            "fullname": "Nome e sobrenome"
            }
        }
    ]
}

Consultar detalhes de uma assinatura

Requisição

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

Resposta

Sucesso

Status: 200 OK
{
    "code": "assinatura01",
    "amount": "9990", // em centavos
    "status": "ACTIVE",
    "creation_date": {
        "day": "20",
        "month": "10",
        "year": "2012",
        "hour": "20",
        "minute": "00",
        "second": "00"
    },
    "next_invoice_date": {
        "day": "20",
        "month": "11",
        "year": "2012"
    },
    "expiration_date": {
        "day": "20",
        "month": "10",
        "year": "2013"
    },
    "plan": {
        "name": "Plano Especial",
        "code": "plano01"
    },
    "customer": {
        "code": "cliente01",
        "fullname": "Nome e Sobrenome",
        "email": "nome@exemplo.com.br"
    }
}

Suspender, reativar e cancelar uma Assinatura

É possível suspender, reativar e cancelar uma Assinatura. Caso suspensa, a assinatura não será cobrada no final do intervalo atual, ao reativá-la, a próxima cobrança será feita de acordo com a data de contratação da assinatura. Caso cancelada, a assinatura não poderá mais ser reativa ou alterada.

Requisição

Suspender

PUT

Reativar

PUT

Cancelar

PUT 

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

Alterar uma assinatura

É possível alterar dados de uma assinatura já criada, tais como o plano, o valor e a data da próxima cobrança.

Requisição

PUT 
Request Method: PUT
Authorization: Basic TOKEN:KEY
Content-Type: application/json
Accept: application/json
{
    "plan": {
        "code": "codigo_do_novo_plano"
    },
    "amount": "9990", // informe apenas se quiser sobrescrever o valor do plano (em centavos)
    "next_invoice_date": {
        "day": "05",
        "month": "01",
        "year": "2013"
    }
}

Atributos que podem ser alterados

Atributo Formato esperado Descrição
plan
└── code "plano01" identificador do novo plano na sua aplicação. Até 65 caracteres. Informe caso queira migrar o plano da assinatura (downgrade/upgrade). Importante: A próxima cobrança ocorrerá na data que já estava pré agendada e será feita no valor do novo plano (seguindo o modelo de assinaturas pré-pagas).
amount 10010 valor em centavos de Real.

Importante: informe apenas se quiser alterar o valor a ser cobrado na assinatura em centavos. Sobrescreverá o valor do plano contratado. A alteração de valor é útil caso queira definir um valor diferente para a assinatura de cliente específico (acrescentar o valor de frete ao plano ou oferecer um desconto, por exemplo). O valor informado será utilizado a partir da próxima fatura.
next_invoice_date Informe se quiser alterar a data na qual será realizada a próxima cobrança.

Importante: apenas a data da próxima cobrança será alterada, as demais cobranças seguirão sendo calculadas de acordo com a configuração inicial da assinatura.

├── day "05" dia do mês no formato dd.
├── month "01" mês no formato MM.
└── year "2013" ano no formato yyyy.
Importante: o assinante deve ser notificado e estar de acordo com qualquer alteração em sua assinatura (plano, valor ou data). O não cumprimento dessa exigência poderá ocasionar a suspensão da utilização dos serviços do Moip Assinaturas.

Status de uma assinatura

1 - "Active"

A assinatura está ativa, ou seja, o cliente assinante será cobrado a cada ciclo.

2 - "Suspended"

As cobranças da assinatura estão suspensas, ou seja, o cliente assinante não será cobrado a cada ciclo.

3 - "Expired"

A assinatura está expirada, ou seja, já atingiu o limite de cobranças configuradas no plano contratado e não gerará mais cobranças.

4 - "Overdue"

A assinatura está com o pagamento de sua fatura atrasada e entrou no fluxo de retentativas. Para saber mais sobre retentativas de pagamentos, clique aqui.

5 - "Canceled"

A assinatura foi cancelada e não poderá mais ser reativada ou editada de nenhuma maneira. Em outras palavras, o cancelamento é a inativação definitiva de uma assinatura.

6 - "Trial"

O trial é um período de testes de uma assinatura, ele pode ter uma taxa de inscrição ou ser gratuito. Para configurar as preferências do seu trial, você deve utilizar a API de Planos ou utilizar a interface do Moip Assinaturas.



(A) - Após criada, a Assinatura gerau uma nova fatura;
(B) - Dentro da fatura, foi criado um novo pagamento;
(C) - O pagamento foi “Iniciado” no Moip Assinaturas;
(D) - O pagamento tem o status “Iniciado” ou “Em análise”, o status da fatura é “Aguardando Confirmação”;
(E) - Enquanto o pagamento e fatura estão no cenário (D), a Assinatura mantém o status “Ativo”.
(F) - Quando o pagamento é “Autorizado” o status da fatura torna-se “Paga” e a Assinatura continua “Ativa”;
(G) - O pagamento que estava “Autorizado”/”Concluído” foi “Estornado” ou “Reembolsado”;
(H) - O pagamento foi “Cancelado”;
(I) - O pagamento “Estornado”/”Reebolsado” mudau o status da fatura para “Não Paga”;
(J) - A terceira retentativa automática de pagamento foi executada, a fatura torna-se “Não paga”;
(K) - O primeiro pagamento da fatura foi cancelado e ela entrou no fluxo de retentativa automática, a fatura torna-se “Atrasada”;
(L) - A primeira ou a segunda ou retentativa de pagamento foi cancelada, a fatura continua no fluxo de retentativa automática;
(M) - A fatura “Paga” mantém a assinatura “Ativa”;
(N) - A fatura “Não Paga”, suspende a assinatura.
(O) - Os cenários (K) ou (L) alteraram o status da assinatura para “Atrasada”;
(P) - Após o prazo determinado no plano a assinatura expirou;
(Q) - Os cenários (K) e (L) foi executada uma retentativa automática.

Faturas de uma assinatura

As assinaturas criadas geram faturas de acordo com as configurações do plano contratado. A partir desta API é possível consultar todas as faturas de uma assinatura e seus detalhes.

Listar todas as faturas de uma assinatura

Requisição

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

Resposta

Sucesso
Status: 200 OK
{
    "invoices": [
        {
            "id": 13,
            "amount": 9990, // em centavos
            "subscription_code": "assinatura7",
            
            "occurrence": 1,
            "status": {
                "code": 2,
                "description": "Aguardando confirmação"
            },
            "creation_date": {
                "day": 28,
                "month": 12,
                "year": 2012,
                "hour": 15,
                "minute": 38,
                "second": 41
            }
        }
    ]
}

Consultar detalhes de uma fatura

Requisição

GET
Você pode obter o ID da cobrança pela requisição "listar cobranças", pelo webhook ou ainda pela área logada. 
Request Method: GET
Authorization: Basic TOKEN:KEY
Content-Type: application/json
Accept: application/json

Resposta

Sucesso
Status: 200 OK
{
    "id": 13,
    "amount": 9990, // em centavos
    "subscription_code": "assinatura7",
    "occurrence": 1,
    "status": {
        "code": 2,
        "description": "Aguardando confirmação"
    },
    "items": [
        {
            "amount": 9990, // em centavos
            "type": "Valor da assinatura"
        },
        {
            "amount": 500, // em centavos
            "type": "Taxa de contratação"
        }
    ],
    "plan": {
        "code": "plano01",
        "name": "Plano Especial"
    },
    "customer": {
        "code": "cliente01",
        "fullname": "Nome Sobrenome"
    },
    "creation_date": {
        "day": 28,
        "month": 12,
        "year": 2012,
        "hour": 15,
        "minute": 38,
        "second": 41
    }
}
Atributos da resposta
Atributo Formato esperado Descrição
id 31 Identificador da fatura no Moip Assinaturas.
amount 1010 Valor total cobrado do cliente, em centavos.
subscription_code "assinatura01" Código da assinatura.
occurence 1 Ocorrência da fatura na assinatura (ex. 3 para a terceira fatura).
status Node de status da fatura. Ver valores possíveis
└── code 2 Código do status
description "Aguardando confirmação" Descrição do status.
items Detalhamento dos itens que compõem a fatura.
├── type "Valor da assinatura" Descrição do item (ex. "Valor da assinatura", "Taxa de contratação", "Período de Trial", etc.)
└── amount 9990 Valor do item, em centavos. Em assinaturas com período de Trial gratuito o valor da primeira fatura é ser 0.
plan Dados do plano referente à fatura.
├── code "plano01" Código do plano contratado.
└── name "Plano 1 real" Nome do plano contratado
customer Node do cliente referente à fatura.
├── code "cliente01" Código do cliente assinante.
└── fullname "Fulano Testador" Nome completo do cliente assinante.
creation_date Data e hora da criação da fatura.
├── day "26" Dia do mês no formato dd.
├── month "09" Mês no formato MM.
├── year "2012" Ano no formato yyyy.
├── hour "16" Horas no formato HH (24hs).
├── minute "00" Minutos no formato mm.
└── second "10" Segundos no formato ss.

Status de uma fatura

É importante conhecer e entender os status da fatura e suas possíveis transições para gerenciar inadimplência e permissão aos serviços contratados em seu sistema.

Código Descrição O que significa?
1 Em aberto A fatura foi gerada mas ainda não foi paga pelo assinante.
2 Aguardando confirmação A fatura foi paga pelo assinante, mas o pagamento está em processo de análise de risco.
3 Pago A fatura foi paga pelo assinante e confirmada.
4 Não pago O assinante tentou pagar a fatura, mas o pagamento foi negado pelo banco emissor do cartão de crédito ou a análise de risco detectou algum problema. Veja os motivos possíveis.
5 Atrasada O pagamento da fatura foi cancelado e serão feitas novas tentativas de cobrança de acordo com a configuração de retentativa automática.
Transições de status:


(A) O pagamento está em análise.
(B) O pagamento foi autorizado.
(C) O pagamento foi cancelado, veja aqui os possíveis motivos.
(D) O pagamento foi cancelado e entrou no fluxo de retentativas.
(E) O pagamento teve um reembolso/chargeback.
(F) O pagamento de retentativa foi cancelado.
(G) O pagamento de retentativa foi autorizado.

Pagamentos

Uma fatura, como é conhecida no mercado, é um conjunto descritivo de itens cobrados em um pré-determinado intervalo de tempo em uma assinatura. O pagamento, por sua vez, é a efetivação da cobrança do valor total de uma fatura.


Para entender melhor, veja o diagrama abaixo:


A assinatura do “Plano Ouro” gerou uma fatura referente à mensalidade de janeiro de 2013.
O Moip Assinaturas realizou o pagamento no cartão de crédito Visa, cadastrado previamente pelo assinante. Como o cartão já estava com o limite de saldo atingido, a administradora de cartões negou o pagamento. O status da fatura foi alterado para “Não pago”.
O vendedor foi notificado e solicitou um nova tentativa de pagamento, agora com o cartão de crédito Mastercard. A administradora de cartões aprovou o pagamento e a análise de risco do Moip autorizou. O status da fatura foi alterado para “Pago”.

Listar todos os pagamentos de uma fatura

Requisição

GET

Você pode obter o ID da cobrança pela requisição "listar cobranças", pelo webhook ou ainda pela área logada. 

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

Resposta

Sucesso
Status: 200 OK
{
    "payments": [
        {
            "id": 6,
            "moip_id": 7205895,
            "status": {
                "code": 6,
                "description": "Em análise"
            },
            "payment_method": {
                "code": 1,
                "description": "Cartão de Crédito",
                "credit_card": {
                    "brand": "VISA",
                    "holder_name": "Fulano Testador",
                    "first_six_digits": "411111",
                    "last_four_digits": "1111",
                    "expiration_month": "03",
                    "expiration_year": "16"
                }
            },
            "creation_date": {
                "day": 28,
                "month": 12,
                "year": 2012,
                "hour": 15,
                "minute": 38,
                "second": 41
            }
        }
    ]
}

Consultar detalhes de um pagamento

Requisição

GET

Você pode obter o ID do pagamento pela requisição "listar pagamentos", pelo webhook ou ainda pela área logada. 

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

Resposta

Sucesso
Status: 200 OK
{
    "id": 6,
    "moip_id": 7205895,
    "status": {
        "code": 6,
        "description": "Em análise"
    },
    "subscription_code": "assinatura7",
    "customer_code": "cliente01",
    "invoice": {
        "id": 13,
        "amount": 9990  // em centavos
    },
    "payment_method": {
        "code": 1,
        "description": "Cartão de Crédito",
        "credit_card": {
            "brand": "VISA",
            "holder_name": "Fulano Testador",
            "first_six_digits": "411111",
            "last_four_digits": "1111",
            "expiration_month": "03",
            "expiration_year": "16"
        }
    },
    "creation_date": {
        "day": 28,
        "month": 12,
        "year": 2012,
        "hour": 15,
        "minute": 38,
        "second": 41
    }
}
Atributos
Atributo Formato esperado Descrição
id 6 Identificador do pagamento no Moip Assinaturas.
moip_id 7205895 Identificador do pagamento no Moip Pagamentos.
status Node de status do pagamento.
Ver valores possíveis.
└── code 6 Código do status.
description "Em análise" Descrição do status.
├── subscription_code "assinatura7" Código da assinatura.
└── customer_code "cliente01" Código do cliente pagador.
invoice Node da fatura
├── id 13 ID da fatura no Moip Assinaturas.
└── amount 101 Valor pago em centavos.
payment_method Node da forma de pagamento.
├── code 1 Código da forma de pagamento.
├── description "Cartão de Crédito" Descrição da forma de pagamento.
├── credit_card Node de dados do cartão de crédito, caso esta seja a forma de pagamento escolhida.
│ ├── brand "VISA" Bandeira do cartão.
│ ├── holder_name Fulano Testador Nome do portador.
│ ├── first_six_digits "411111" Primeiros 6 dígitos. .
│ ├── last_four_digits "1111" Últimos 4 dígitos.
│ ├── expiration_month "03" Mês de expiração. Formato MM.
└─└──expiration_year "16" Ano de expiração. Formato yy.
creation_date Data e hora da criação da cobrança.
├── day "26" Dia do mês no formato dd.
├── month "09" Mês no formato MM.
├── year "2013" Ano no formato YYYY.
├── hour "16" Horas no formato HH (24hs).
├── minute "00" Minutos no formato mm.
└── second "10" Segundos no formato ss.

Status de um pagamento

Os status de pagamento no Assinaturas seguem o padrão Moip.

Atributo Formato esperado Descrição
1 Autorizado O pagamento foi autorizado pelo banco e pela análise de risco. O valor será creditado de acordo com o prazo de recebimento da sua conta Moip.
2 Iniciado O pagamento foi criado, mas ainda não foi autorizado pelo banco.
3 Boleto impresso O assinante optou pelo pagamento com boleto bancário, mas o banco ainda não confirmou a liquidação do mesmo.
Importante: ainda não há pagamento por boleto para o Moip Assinaturas. Esse código não será informado no momento.
4 Concluído O pagamento foi concluído e o valor líquido já está disponível para saque em sua conta Moip.
5 Cancelado O pagamento foi negado pelo banco ou pela análise de risco. Este é um estado final do pagamento.
6 Em análise O pagamento foi autorizado pelo banco e está sendo analisado pelo setor de Análise de Risco. Este é um status temporário com tempo limite de 48 horas.
7 Estornado O pagamento foi revertido pelo banco por solicitação do assinante.
9 Reembolsado O valor foi reembolsado para o assinante por solicitação dele ou do vendedor.

Retentativas

O Moip Assinaturas possibilita recuperar pagamentos de suas assinaturas pela interface e pela API.

Retentar um pagamento

Após um pagamento ser cancelado é possível fazer uma nova tentativa de cobrança com o mesmo cartão que seu cliente já possui, ou efetuar uma retentativa após atualizar os dados do Cartão com a API de Clientes.

Requisição

POST 
Request Method: POST
Authorization: Basic TOKEN:KEY
Content-Type: application/json
Accept: application/json
Importante: O limite diário de retentativas é de 3 tentativas/dia por fatura.

Criar regras de retentativas automáticas

Além de tentar reprocessar um pagamento manualmente via interface ou através de uma requisição na API, é possível configurar retentativas automáticas a partir das quais o Moip vai reprocessar seus pagamentos de acordo com suas preferências.
Essas retentativas são aplicadas a todas as cobranças recorrentes, porém, não ocorrem na primeira ocorrência de cobrança (primeira fatura gerada).

Importante: O limite diário de retentativas é de 3 tentativas/dia por invoice, independente se essa é uma tentativa automática (feita pelo Moip Assinaturas) ou manual (feita pelo cliente). Caso as retentativas automáticas não sejam configuradas, a assinatura será automaticamente suspensa após o primeiro cancelamento.

Você pode determinar até três tentativas de cobrança de uma fatura em atraso. Leia mais sobre faturas em status atrasada.

Requisição

POST 
Request Method: POST
Authorization: Basic TOKEN:KEY
Content-Type: application/json
Accept: application/json
{
    "first_try": 1,
    "second_try": 3,
    "third_try": 5,
    "finally": "cancel"
}

As datas das retentativas são calculadas com base na tentativa anterior, podendo ser configuradas de acordo com a tabela abaixo:

Parâmetros
parâmetro valor
first_try, second_try, third_try, finally 1, 3, 5, 7 dias após a tentativa anterior.
suspend e cancel deixam de executar a retentativa e alteram o status da Assinatura.

Assim, o intervalo mínimo de retentativa automática é de 1 dia e o máximo de 22 dias.

Importante: Recomendamos que o intervalo total de retentativas seja sempre inferior ao seu plano com a menor periodicidade de cobranças. Por exemplo, se seu plano for quinzenal, configure suas retentativas para um intervalo total de no máximo 14 dias, evitando assim efetuar duas cobranças autorizadas em períodos muito curtos de tempo.

Preferências

Você pode alterar algumas das preferências de sua conta também através de uma requisição via API. As configurações que podem ser alteradas são: envio de e-mails ao vendedor, envio de e-mails ao assinante e URL de notificação.

Com a API de preferências você pode:

Configurar preferências de notificação

Requisição

POST 
Request Method: POST
Authorization: Basic TOKEN:KEY
Content-Type: application/json
Accept: application/json
{
    "notification": {
        "webhook": {
            "url": "http://exemploldeurl.com.br/assinaturas"
        },
        "email": {
            "merchant": {
                "enabled": true
            },
            "customer": {
                "enabled": true
            }
        }
    }
}