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 do tipo cartão de crédito
  • a cobrança deve ter o status unpaid


    • Assinatura Cancelada ou Desativada

    Caso uma assinatura esteja cancelada ou desativada, e uma nova tentativa de pagamento for realizada com sucesso na última cobrança pendente, a assinatura será automaticamente reativada.


    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
    }
    Última atualização em