Pular para o conteúdo principal

Assinatura

Introdução sobre a funcionalidade de Assinaturas (Recorrência) na API Efí


Introdução

Realize cobranças recorrentes aos seus clientes por meio de planos de assinaturas. Com essa opção, seus clientes autorizam os débitos e você não precisa se preocupar em enviar cobranças a cada mês, evitando o risco de esquecimentos de pagamento.

Uma assinatura é um conjunto de transações geradas de forma recorrente. Para criar uma assinatura, você deve gerar uma cobrança e incluir informações sobre o número de parcelas e a periodicidade em que o sistema deve gerar transações iguais à primeira. Essas informações são chamadas de Planos de Assinaturas.

Uma assinatura é caracterizada pela cobrança recorrente, podendo ser realizada por boleto ou cartão:

  • Cartão de Crédito: seu cliente irá informar os dados de pagamento e a cobrança será debitada de acordo com a configuração do plano. O valor será descontado até que todas as parcelas sejam pagas ou até que a assinatura seja cancelada por você ou pelo cliente. Para calcular os limites do cartão, consideramos o valor mensal, não o total da cobrança com todas as parcelas.

  • Boleto Bancário: seu cliente receberá a cobrança por e-mail 10 dias antes do vencimento até que termine a quantidade de parcelas solicitadas ou até que você ou seu cliente cancele a assinatura. Se a cobrança automática cair num fim de semana ou feriado, nosso sistema vai gerar, automaticamente, uma cobrança com data de vencimento para o próximo dia útil.

Para criar uma assinatura, siga esses três passos:

  1. Crie o plano de assinatura, definindo a periodicidade e quantas cobranças serão geradas;

  2. Crie inscrições (assinaturas) para vincular ao plano em One Step ou Two Steps;

  3. Defina a forma de pagamento da assinatura e insira os dados do cliente.


Como funciona

Uma assinatura é criada com status new indicando que está pronta para ser ativada. Assim que a forma de pagamento é definida, o status muda para active, mostrando que a assinatura está ativa e pronta para gerar cobranças recorrentes.

A assinatura permanecerá ativa durante todo o ciclo de geração de cobranças, mas pode deixar de ser ativa por três motivos:

  • A pessoa pagadora cancelou o serviço, clicando no link de cancelamento presente no e-mail de confirmação de assinatura. Assim, o status é alterado para canceled;

  • O vendedor cancelou o serviço, clicando no link de cancelamento presente em sua interface de recebimentos, ou por meio do webservice de cancelamento através do endpoint /subscription/cancel ou função cancelSubscription da SDK. Assim, o status é alterado para canceled;

  • Todas as cobranças já foram geradas. Assim, o status é alterado para expired, ou seja, a assinatura está expirada e todas as cobranças configuradas para a assinatura já foram emitidas.

Para acompanhar a assinatura, é importante observar os status das transações geradas. Se uma transação não puder ser confirmada como paga, o status será unpaid, , indicando que o pagamento não foi concluído. Nesse caso, o vendedor deve tomar ações apropriadas, como interromper o serviço, tentar cobrar de outra forma ou cancelar a assinatura.

As duas formas de pagamento disponíveis são: boleto e cartão. Com o boleto, o cliente recebe o boleto com base nas repetições definidas no plano, e ele pode ser enviado por e-mail. Com o cartão, a cobrança é debitada automaticamente do cartão do cliente, seguindo as repetições do plano.

Tanto a pessoa que fez a assinatura quanto o vendedor podem cancelar a assinatura a qualquer momento. Quando isso ocorre, ambos são avisados via e-mail, com todos os detalhes do cancelamento.


Crie o plano de assinatura

Inicialmente, será criado o plano de assinatura, sendo definido três informações pelo integrador:

  • name - Nome do plano de assinatura;
  • interval (em meses) - Periodicidade da cobrança (por exemplo, 1 para mensal);
  • repeats - Quantas cobranças devem ser geradas para esse plano.

Para criar um plano de assinatura, você deve enviar uma requisição POST para a rota /plan.

POST /v1/plan
Requer ativação da API de Emissão de cobranças em sua aplicação


Requisição

{
"name": "Plano de Internet - Velocidade 10 Mb",
"interval": 1,
"repeats": 12
}

Respostas

A resposta abaixo representa Sucesso do consumo.

{
"code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
"data": {
"plan_id": numero_plan_id, // número da ID referente ao plano de assinatura criado
"name": "Plano de Internet - Velocidade 10 Mb", // nome do plano de assinatura
"interval": 12, // intervalo que as cobranças devem ser geradas, em meses
"repeats": null, // número de vezes que a cobrança deve ser gerada - neste caso, indefinidamente
"created_at": "2016-06-28 15:48:32" // data e hora da criação da transação
}
}

Retentativa de pagamento de assinatura via cartão de crédito

Os pagamentos das assinaturas realizados via cartão de crédito, que forem recusados por algum motivo operacional, como falta de limite, dados incorretos e problemas temporários com o cartão, poderão ter uma nova tentativa de pagamento via API.

Dessa forma, não será necessário realizar todo o processo de emissão da cobrança novamente, tornando o fluxo mais rápido e eficiente.

POST /v1/charge/:id/retry
Requer ativação da API de Emissão de cobranças em sua aplicação


Requisição

{
"payment": {
"credit_card": {
"customer": {
"name": "Gorbadoc Oldbuck",
"cpf": "94271564656",
"email": "[email protected]",
"birth": "1990-08-29",
"phone_number": "5144916523"
},
"billing_address": {
"street": "Avenida Juscelino Kubitschek",
"number": "909",
"neighborhood": "Bauxita",
"zipcode": "35400000",
"city": "Ouro Preto",
"complement": "",
"state": "MG"
},
"payment_token": "75bfce47d230b550f7eaac2a932e0878a934cb3",
"update_card": true
}
}
}

Respostas

As respostas abaixo representam Sucesso do consumo.

{
"code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
"data": {
"installments": 1, // número de parcelas em que o pagamento deve ser dividido
"installment_value": 8900, // valor da parcela. Por exemplo: 8900 (equivale a R$ 89,00)
"charge_id": numero_charge_id, // número da ID referente à transação gerada
"status": "waiting", // forma de pagamento selecionada, aguardando a confirmação do pagamento ("waiting" equivale a "aguardando")
"total": 8900, // valor, em centavos. Por exemplo: 8900 (equivale a R$ 89,00)
"payment": "credit_card" // forma de pagamento associada à esta transação ("credit_card" equivale a "cartão de crédito")
}
}

Informação

Esta funcionalidade permite que o integrador tente reprocessar uma cobrança de assinatura que falhou. Para isso, a cobrança deve atender aos seguintes critérios:

  • a cobrança deve ser de cartão de crédito
  • a cobrança deve ter o status unpaid

  • Retornar informações de um plano

    Você pode buscar informações sobre os planos criados. Existem filtros avançados que podem ser usados para encontrar planos, como:

    • Name: retorna resultados a partir da procura pelo nome do plano cadastrado previamente;
    • Limit: limite máximo de registros de resposta;
    • Offset: determina a partir de qual registro a busca será realizada.
    GET /v1/plans
    Requer ativação da API de Emissão de cobranças em sua aplicação


    Requisição

    Parâmetro de entrada: informe a "name", "limit" e "offset" do plano desejado

    Respostas

    As respostas abaixo representam Sucesso(200) do consumo.

    {
    "code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
    "data": [
    {
    "plan_id": numero_plan_id, // número da ID referente ao plano de assinatura criado
    "name": "Plano de Internet - Velocidade 1 Mb", // nome do plano de assinatura
    "interval": 1, // intervalo que as cobranças devem ser geradas, em meses
    "repeats": null, // número de vezes que a cobrança deve ser gerada - neste caso, indefinidamente
    "created_at": "2016-05-02" // data e hora da criação da transação
    },
    {
    "plan_id": numero_plan_id, // número da ID referente ao plano de assinatura criado
    "name": "Plano de Internet - Velocidade 10 Mb", // nome do plano de assinatura
    "interval": 12, // intervalo que as cobranças devem ser geradas, em meses
    "repeats": null, // número de vezes que a cobrança deve ser gerada - neste caso, indefinidamente
    "created_at": "2016-06-28" // data e hora da criação da transação
    },
    {
    "plan_id": numero_plan_id, // número da ID referente ao plano de assinatura criado
    "name": "Plano de Internet - Velocidade 20 Mb", // nome do plano de assinatura
    "interval": 10, // intervalo que as cobranças devem ser geradas, em meses
    "repeats": null, // número de vezes que a cobrança deve ser gerada - neste caso, indefinidamente
    "created_at": "2016-06-29" // data e hora da criação da transação
    },
    {
    "plan_id": numero_plan_id, // número da ID referente ao plano de assinatura criado
    "name": "Plano de Internet - Velocidade 30 Mb", // nome do plano de assinatura
    "interval": 12, // intervalo que as cobranças devem ser geradas, em meses
    "repeats": null, // número de vezes que a cobrança deve ser gerada - neste caso, indefinidamente
    "created_at": "2016-06-29" // data e hora da criação da transação
    }
    ]
    }

    Permitir a edição do nome do plano de assinatura

    Você pode editar o nome de um plano de assinatura que já foi criado. Para fazer isso, basta fornecer o identificador do plan_id do plano que deseja editar.

    PUT /v1/plan/:id
    Requer ativação da API de Emissão de cobranças em sua aplicação


    Requisição

    {
    "name": "Meu novo nome do plano"
    }

    Respostas

    As respostas abaixo representam Sucesso(201) do consumo.

    {
    "code": 200 // retorno HTTP "200" informando que o pedido foi bem sucedido
    }

    Cancelar um plano de assinatura

    Você pode cancelar um plano de assinatura a qualquer momento. Para isso, basta informar o plan_id do plano que deseja cancelar.

    DELETE/v1/plan/:id
    Requer ativação da API de Emissão de cobranças em sua aplicação


    Requisição

    Parâmetro de entrada: informe a "charge_id" da transação desejada

    Respostas

    As respostas abaixo representam Sucesso(201) do consumo.

    {
    "code": 200 // retorno HTTP "200" informando que o pedido foi bem sucedido
    }

    Crie inscrições (assinaturas) para vincular ao plano em One Step

    Após criar o plano, é hora de criar as assinaturas e vinculá-las ao plano. As assinaturas são úteis quando você precisa cobrar seus clientes de forma recorrente. Com o plano configurado, os custos futuros serão criados automaticamente, seguindo a configuração do plano.

    Lembre-se de informar o plan_id do plano que você criou anteriormente para fazer a associação.

    Para criar e vincular as assinaturas, basta enviar uma requisição POST para a rota /plan/:id/subscription/one-step.

    Atributo "trial_days" que permite conceder um período de teste

    A API oferece o atributo trial_days, que permite definir um período de teste gratuito para assinaturas do tipo cartão de crédito. Esse atributo está disponível somente quando o pagamento é realizado com credit_card.


    Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
    "items"  
    "name"
    "value"
    "amount"
    "shippings"
    "name"
    "value"
    "payee_code"
    "metadata"
    "custom_id"
    "notification_url"
    "payment"
    "banking_billet"
    "customer"
    "name"
    "cpf"
    "email"
    "phone_number"
    "birth"
    "address"
    "street"
    "number"
    "neighborhood"
    "zipcode"
    "city"
    "complement"
    "state"
    "juridical_person"
    "corporate_name"
    "cnpj"
    "expire_at"
    "discount"
    "type"
    "percentage"
    "currency"
    "value"
    "conditional_discount"
    "type"
    "percentage",
    "currency"
    "value"
    "until_date"
    "configurations"
    "fine"
    "interest"
    "message"
    "credit_card"
    "customer"
    "name"
    "cpf"
    "email"
    "phone_number"
    "birth"
    "address"
    "street"
    "number"
    "neighborhood"
    "zipcode"
    "city"
    "complement"
    "state"
    "juridical_person"
    "corporate_name"
    "cnpj"
    "billing_address"
    "street"
    "number"
    "neighborhood"
    "zipcode"
    "city"
    "complement"
    "state"
    "payment_token"
    "discount"
    "type"
    "percentage"
    "currency"
    "value"
    "message"
    "trial_days"
    POST /v1/plan/:id/subscription/one-step
    Atributos

    Nesta seção estão descritos os atributos para Assinatura do tipo Boleto (Objeto banking_billet) e Cartão de crédito (Objeto credit_card)


    Requer ativação da API de Emissão de cobranças em sua aplicação


    Requisição

    {
    "items": [
    {
    "name": "Meu Produto",
    "value": 5990,
    "amount": 1
    }
    ],
    "payment": {
    "banking_billet": {
    "customer": {
    "name": "Gorbadoc Oldbuck",
    "cpf": "94271564656",
    "email": "[email protected]",
    "phone_number": "5144916523",
    "address": {
    "street": "Avenida Juscelino Kubitschek",
    "number": "909",
    "neighborhood": "Bauxita",
    "zipcode": "35400000",
    "city": "Ouro Preto",
    "complement": "",
    "state": "MG"
    }
    },
    "expire_at": "2023-12-30",
    "configurations": {
    "fine": 200,
    "interest": 33
    },
    "message": "Pague pelo código de barras ou pelo QR Code"
    }
    }
    }

    Respostas

    As respostas abaixo representam Sucesso do consumo.

    {
    "code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
    "data": {
    "subscription_id": 25329, // número ID referente à inscrição gerada
    "status": "active", // assinatura ativa - todas as cobranças estão sendo geradas
    "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000",
    "link": "link_do_boleto_da_assinatura", // link responsivo do boleto gerado
    "billet_link":"link_https_para_acesso_o_bolix", // link do boleto gerado
    "pdf": {
    "charge": "link_pdf_boleto_assinatura" // link do PDF boleto gerado da assinatura
    },
    "expire_at": "2018-12-30", // data de vencimento do boleto no seguinte formato: 2018-12-30 (ou seja, equivale a 30/12/2018)
    "plan": {
    "id": 2758, // número da ID referente ao plano de assinatura criado
    "interval": 1, // periodicidade da cobrança (em meses) - informe 1 para assinatura mensal
    "repeats": null // número de vezes que a cobrança deve ser gerada
    //(padrão: null, que significa que a cobrança é gerada por tempo indeterminado ou até que o plano seja cancelado)
    },
    "charge": {
    "id": 511843, // número da ID referente à transação gerada
    "status": "waiting", // forma de pagamento selecionada, aguardando a confirmação do pagamento
    "parcel": 1,
    "total": 7900
    },
    "first_execution": "31/10/2018", // data da primeira execução da assinatura
    "total": 7900,
    "payment": "banking_billet" // forma de pagamento (banking_billet equivale a boleto)
    }
    }

    Crie inscrições (assinaturas) para vincular ao plano em Two Steps

    Primeiramente, é necessário criar a assinatura e vinculá-la ao plano. Você deve informar o item/produto/serviço, valor e quantidade para criar a assinatura. Em seguida, defina a forma de pagamento da assinatura e os dados do cliente, informando o charge_id da transação e os dados do cliente.

    1. Crie inscrições (assinaturas) para vincular ao plano

    Com o plano criado, é hora de criar as assinaturas e associá-las aos planos. As assinaturas são úteis quando você precisa cobrar seus clientes de forma recorrente. Dessa forma, os custos subsequentes serão criados automaticamente, seguindo a configuração do plano.

    Lembre-se de informar o plan_iddo plano que você criou anteriormente para fazer a associação.

    Para associar assinaturas aos planos, basta enviar uma requisição POST para a rota /plan/:id/subscription.

    Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
    "items"  
    "name"
    "value"
    "amount"
    "shippings"
    "name"
    "value"
    "payee_code"
    "metadata"
    "custom_id"
    "notification_url"
    POST /v1/plan/:id/subscription
    Requer ativação da API de Emissão de cobranças em sua aplicação


    Requisição

    {
    "items": [
    {
    "name": "Internet - Mensalidade",
    "value": 6990,
    "amount": 1
    }
    ]
    }

    Respostas

    As respostas abaixo representam Sucesso do consumo.

    {
    "code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
    "data": {
    "subscription_id": numero_subscription_id, // número ID referente à inscrição gerada
    "status": "new", // cobrança gerada, aguardando definição da forma de pagamento
    "custom_id": null, // identificador próprio opcional
    "charges": [
    {
    "charge_id": numero_charge_id, // número da ID referente à transação gerada
    "status": "new", // cobrança gerada, aguardando definição da forma de pagamento
    "total": 6990, // valor total da transação (em centavos, sendo 6990 = R$69,90)
    "parcel": 1 // número de parcelas
    }
    ],
    "created_at": "2016-06-29 10:42:59" // data e hora da criação da transação
    }
    }

    2. Defina a forma de pagamento da assinatura e os dados do cliente

    Após criar o plano de assinatura e vincular as assinaturas aos planos, é hora de definir a forma de pagamento recorrente das assinaturas. Isso pode ser feito através de boleto bancário ou cartão de crédito.

    • Cartão de Crédito: seu cliente realiza o pagamento, de acordo com a periodicidade que você definiu (mensal, trimestral, etc) no plano, sendo o mesmo valor cobrado automaticamente em seu cartão de crédito de seu cliente. Na recorrência por cartão, seu cliente digita os dados do cartão apenas no primeiro pagamento, depois a cobrança é realizada automaticamente sem que ele precise informar os dados novamente;
    Assinatura do tipo Cartão de crédito

    Para gerar uma assinatura do tipo Cartão de crédito, é necessário antes de consumir o endpoint POST /v1/subscription/:id/pay, obter o payment_token. Você pode ver mais detalhes em Obtenção do payment_token.


    • Boleto Bancário: será gerado conforme o número de repetições definido pelo plano, podendo ser enviado por e-mail.Tanto a pessoa que fez a assinatura quanto o vendedor podem cancelar a assinatura a qualquer momento. Quando isso ocorre, ambos são avisados via e-mail, com todos os detalhes do cancelamento.
    Atributo "trial_days" que permite conceder um período de teste

    A API oferece o atributo trial_days, que permite definir um período de teste gratuito para assinaturas do tipo cartão de crédito. Esse atributo está disponível somente quando o pagamento é realizado com credit_card.


    Para associar assinaturas à forma de pagamento, você deve enviar uma requisição POST para a rota /subscription/:id/pay.

    Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
    "payment"  
    "banking_billet"
    "customer"
    "name"
    "cpf"
    "email"
    "phone_number"
    "birth"
    "address"
    "street"
    "number"
    "neighborhood"
    "zipcode"
    "city"
    "complement"
    "state"
    "juridical_person"
    "corporate_name"
    "cnpj"
    "expire_at"
    "discount"
    "type"
    "percentage"
    "currency"
    "value"
    "conditional_discount"
    "type"
    "percentage",
    "currency"
    "value"
    "until_date"
    "configurations"
    "fine"
    "interest"
    "message"
    "credit_card"
    "customer"
    "name"
    "cpf"
    "email"
    "phone_number"
    "birth"
    "address"
    "street"
    "number"
    "neighborhood"
    "zipcode"
    "city"
    "complement"
    "state"
    "juridical_person"
    "corporate_name"
    "cnpj"
    "billing_address"
    "street"
    "number"
    "neighborhood"
    "zipcode"
    "city"
    "complement"
    "state"
    "payment_token"
    "discount"
    "type"
    "percentage"
    "currency"
    "value"
    "message"
    "trial_days"
    POST /v1/subscription/:id/pay
    Requer ativação da API de Emissão de cobranças em sua aplicação


    Requisição

    {
    "payment": {
    "banking_billet": {
    "customer": {
    "name": "Gorbadoc Oldbuck",
    "cpf": "94271564656",
    "email": "[email protected]",
    "phone_number": "5144916523",
    "address": {
    "street": "Avenida Juscelino Kubitschek",
    "number": "909",
    "neighborhood": "Bauxita",
    "zipcode": "35400000",
    "city": "Ouro Preto",
    "complement": "",
    "state": "MG"
    }
    },
    "expire_at": "2023-12-30",
    "configurations": {
    "fine": 200,
    "interest": 33
    },
    "message": "Pague pelo código de barras ou pelo QR Code"
    }
    }
    }

    Respostas

    As respostas abaixo representam Sucesso do consumo.

    {
    "code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
    "data": {
    "subscription_id": 25329, // número ID referente à inscrição gerada
    "status": "active", // assinatura ativa - todas as cobranças estão sendo geradas
    "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000",
    "link": "link_do_boleto_da_assinatura", // link responsivo do boleto gerado
    "billet_link":"link_https_para_acesso_o_bolix", // link do boleto gerado
    "pdf": {
    "charge": "link_pdf_boleto_assinatura" // link do PDF boleto gerado da assinatura
    },
    "expire_at": "2018-12-30", // data de vencimento do boleto no seguinte formato: 2018-12-30 (ou seja, equivale a 30/12/2018)
    "plan": {
    "id": 2758, // número da ID referente ao plano de assinatura criado
    "interval": 1, // periodicidade da cobrança (em meses) - informe 1 para assinatura mensal
    "repeats": null // número de vezes que a cobrança deve ser gerada
    //(padrão: null, que significa que a cobrança é gerada por tempo indeterminado ou até que o plano seja cancelado)
    },
    "charge": {
    "id": 511843, // número da ID referente à transação gerada
    "status": "waiting", // forma de pagamento selecionada, aguardando a confirmação do pagamento
    "parcel": 1,
    "total": 7900
    },
    "first_execution": "31/10/2018", // data da primeira execução da assinatura
    "total": 7900,
    "payment": "banking_billet" // forma de pagamento (banking_billet equivale a boleto)
    }
    }

    Retornar informações de uma assinatura vinculada a um plano

    Essa funcionalidade permite obter informações de uma assinatura vinculada a um plano específico.

    GET /v1/subscription/:id
    Requer ativação da API de Emissão de cobranças em sua aplicação


    Requisição

    Parâmetro de entrada: informe a "subscription_id" da transação desejada

    Respostas

    As respostas abaixo representam Sucesso(200) do consumo.

    {
    "code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
    "data": {
    "subscription_id": numero_subscription_id, // número ID referente à inscrição gerada
    "value": 6990, // valor da inscrição (6990 equivale a R$69,90)
    "status": "new", // cobrança gerada, aguardando definição da forma de pagamento
    "custom_id": null, // identificador próprio opcional
    "notification_url": null, // endereço da sua URL que receberá as notificações de mudanças de status das transações
    "payment_method": null, // método de pagamento (null = ainda não foi definido), (banking_billet = boleto bancário) ou (credit_card = cartão de crédito)
    "next_execution": null, // data da próxima execução
    "next_expire_at": null, // data do próximo vencimento no formato 2016-12-30
    "plan": {
    "plan_id": numero_plan_id, // número ID referente ao plano de assinatura criado
    "name": "Plano de Internet - Velocidade 10 Mb", // nome do plano de assinatura
    "interval": 12, // intervalo que as cobranças devem ser geradas, em meses
    "repeats": null // número de vezes que a cobrança deve ser gerada - neste caso, indefinidamente
    },
    "occurrences": 0,
    "created_at": "2016-06-29 10:42:59", // data e hora da criação da transação
    "history": [
    {
    "charge_id": numero_charge_id, // número da ID referente à transação gerada
    "status": "new", // cobrança gerada, aguardando definição da forma de pagamento
    "created_at": "2016-06-29 10:42:59" // data e hora da criação da transação
    }
    ]
    }
    }

    Após criar o seu plano de Assinatura, você pode gerar um link de pagamento para associar assinaturas a esse plano. Para fazer isso, envie uma requisição POST para a rota /v1/plan/:id/subscription/one-step/link.

    Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
    "items"  
    "name"
    "value"
    "amount"
    "marketplace"
    "payee_code"
    "percentage"
    "shippings"
    "name"
    "value"
    "payee_code"
    "metadata"
    "custom_id"
    "notification_url"
    "settings"
    "billet_discount"
    "card_discount"
    "conditional_discount"
    "type"
    "percentage",
    "currency"
    "value"
    "until_date"
    "message"
    "expire_at"
    "request_delivery_address"
    "payment_method"
    "banking_billet"
    "credit_card"
    "all"
    POST /v1/plan/:id/subscription/one-step/link
    Atributos

    Nesta seção estão descritos os atributos para Assinatura do tipo Boleto (Objeto banking_billet) e Cartão de crédito (Objeto credit_card)


    Requer ativação da API de Emissão de cobranças em sua aplicação


    Requisição

    {
    "items": [
    {
    "amount": 2,
    "name": "Silicon Valley",
    "value": 564
    }
    ],
    "metadata": {
    "custom_id": "Assinatura",
    "notification_url": "sua_url_notificação"
    },

    "settings": {
    "payment_method": "all" ,
    "expire_at": "2025-02-08",
    "request_delivery_address": true
    }
    }

    Respostas

    As respostas abaixo representam Sucesso do consumo.

    {
    "code": 200,
    "data": {
    "subscription_id": 8021,
    "status": "new",
    "custom_id": "Assinatura",
    "charge": {
    "id": 371496106,
    "status": "link",
    "total": 1128,
    "parcel": 1
    },
    "payment_url": "https://pagamento.gerencianet.com.br/:identificador",
    "payment_method": "all",
    "conditional_discount_date": null,
    "request_delivery_address": true,
    "expire_at": "2025-02-08",
    "created_at": "2021-11-09 12:06:54"
    }
    }

    Incluir "notification_url" e "custom_id" em uma assinatura existente

    É possível definir ou alterar as informações enviadas na propriedade metadata da transação a qualquer momento. Isso é útil para atualizar a URL de notificação vinculada às transações ou modificar o custom_id previamente associado às suas transações.

    Para fazer essas alterações, você deve enviar uma requisição PUT para a rota /v1/charge/:id/metadata, onde :id é o charge_id da transação que deseja atualizar.

    Casos de uso deste endpoint:
    1. A pessoa integradora alterou o IP do servidor que estava associado na URL de notificação das transações;
    2. A pessoa integradora atualizou a URL de notificação para as novas transações criadas (createCharge), mas precisa atualizar também as transações anteriores (updateChargeMetadata) que foram geradas e que estão associadas com a URL incorreta/desatualizada;
    3. Foi instalado SSL (https) no servidor do cliente e mesmo que o cliente defina uma regra de redirecionamento 301 ou 302, será necessário definir a nova URL nas transações que estão usando a URL "antiga";
    4. Integrador gerou cobranças sem informar a URL de notificação ao enviar a requisição de criação da transação;
    5. Modificar ou acrescentar uma informação junto ao atributo custom_id associado às transações geradas previamente; e outros cenários possíveis.
    PUT /v1/subscription/:id/metadata
    Requer ativação da API de Emissão de cobranças em sua aplicação


    Requisição

    {
    "notification_url": 'http://seu_dominio.com/notification',
    "custom_id": 'REF0001'
    }

    Respostas

    As respostas abaixo representam Sucesso(201) do consumo.

    {
    "code": 200 // retorno HTTP "200" informando que o pedido foi bem sucedido
    }

    Alterar dados de uma assinatura

    Você pode editar assinaturas ativas em um plano de assinaturas. Para isso, basta informar os campos que deseja editar e o subscription_id da assinatura.

    Para realizar a alteração da assinatura, envie uma requisição PUT para a rota /v1/subscription/:id com as informações atualizadas no body.

    Somente assinaturas do tipo Cartão de Crédito podem ser alteradas.

    Para alterar os dados de uma assinatura existente, é necessário que o método de pagamento definido seja cartão de crédito.


    PUT /v1/subscription/:id
    Requer ativação da API de Emissão de cobranças em sua aplicação


    Requisição

    { 
    "plan_id": 3,
    "customer": {
    "email": "[email protected]",
    "phone_number": "31123456789"
    },
    "items": [{
    "name": "Product 1",
    "value": 1000,
    "amount": 1
    }],
    "shippings": [{
    "name": "frete",
    "value": 1800
    }]
    }

    Respostas

    As respostas abaixo representam Sucesso(201) do consumo.

    {
    "code": 200,
    "data": {
    "subscription_id": 1,
    "status": "active",
    "value": 2800,
    "custom_id": null,
    "notification_url": null,
    "payment_method": "credit_card",
    "next_execution": "2024-01-05",
    "next_expire_at": "2024-01-05",
    "plan": {
    "plan_id": 3,
    "name": "Novo plano",
    "interval": 1,
    "repeats": 12
    },
    "customer": {
    "email": "[email protected]",
    "phone_number": "31123456789"
    },
    "occurrences": 1,
    "created_at": "2023-12-05T13:47:03.000Z"
    }
    }

    Cancelar uma assinatura

    Você pode cancelar assinaturas ativas em um plano de assinaturas. Para isso, basta informar o subscription_id da assinatura que deseja cancelar.

    Para realizar o cancelamento da assinatura, envie uma requisição PUT para a rota /v1/subscription/:id/cancel da assinatura que você quer cancelar.

    PUT /v1/subscription/:id/cancel
    Requer ativação da API de Emissão de cobranças em sua aplicação


    Requisição

    Parâmetro de entrada: informe a "subscription_id" da transação desejada

    Respostas

    As respostas abaixo representam Sucesso(201) do consumo.

    {
    "code": 200 // retorno HTTP "200" informando que o pedido foi bem sucedido
    }

    Acrescentar descrição ao histórico de uma assinatura

    O histórico de uma assinatura registra todas as ações que ocorreram com ela até o momento atual. Você pode adicionar mensagens personalizadas a esse histórico usando o endpoint /v1/subscription/:id/history.

    As mensagens personalizadas não têm impacto na assinatura em si, apenas são adicionadas ao histórico dela. Para isso, você deve informar o subscription_idda assinatura desejada. Essa descrição deve ter pelo menos um caractere e no máximo 255 caracteres.

    POST/v1/subscription/:id/history
    Requer ativação da API de Emissão de cobranças em sua aplicação


    Requisição

    {
    "description": "Minha mensagem do histórico aqui"
    }

    Respostas

    As respostas abaixo representam Sucesso do consumo.

    {
    "code": 200 // retorno HTTP "200" informando que o pedido foi bem sucedido
    }

    Um link de pagamento associado a um plano pode ser reenviado por e-mail. Para fazer isso, você só precisa enviar o identificador charge_id do link e o endereço de e-mail válido para o qual deseja enviar o boleto.

    Para reenviar o link por e-mail, basta fazer uma requisição POST para a rota /v1/charge/:id/subscription/resend.

    POST /v1/charge/:id/subscription/resend
    Requer ativação da API de Emissão de cobranças em sua aplicação


    Requisição

    {
    "email": "[email protected]"
    }

    Respostas

    As respostas abaixo representam Sucesso do consumo.

    {
    "code": 200 // retorno HTTP "200" informando que o pedido foi bem sucedido
    }