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
  }
}

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
}

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