Create subscription

Learn how to generate a set of recurring charges for your customers. To create a subscription, it is quite simple and requires only three steps:

Create the subscription plan, defining the frequency and how many charges should be generated;
Create subscriptions to link to a plan;
Define subscription payment method and customer data.

Once you've created your subscription plan(s), you will only need to perform the second and third steps for each subsequent subscription.

The rest of this page presents the three detailed steps, but you need to install one of our libraries on your server to run the sample code. Make sure the Gerencianet SDK has been installed.

Bolix

If you have activated Bolix in your Gestornet account, the charges generated by our module/plugin will already come with the pix in the boleto. More details about Bolix and how to activate it, click here.

1. Create a subscription plan

Initially, the subscription plan will be created, in which the integrator can define three pieces of information:

Name of the plan;
Frequency of billing (eg 1 for monthly);
How many charges should be generated.

To create a subscription plan, you must send a POST request to the /plan route.

If you want, you can explore and learn more about this feature using our Playground.

The example below shows how this can be done, using the SDK's available:

<?php
 
require __DIR__.'/../../vendor/autoload.php'; // caminho relacionado a SDK
 
use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;
 
$clientId = 'informe_seu_client_id'; // insira seu Client_Id, conforme o ambiente (Des ou Prod)
$clientSecret = 'informe_seu_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod)
 
$options = [
  'client_id' => $clientId,
  'client_secret' => $clientSecret,
  'sandbox' => true // altere conforme o ambiente (true = desenvolvimento e false = producao)
];
 
$body = [
  'name' => 'Meu Plano de Assinatura', // nome do plano de assinatura
  '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)
];
 
try {
    $api = new Gerencianet($options);
    $plan = $api->createPlan([], $body);
 
    print_r($plan);
} catch (GerencianetException $e) {
    print_r($e->code);
    print_r($e->error);
    print_r($e->errorDescription);
} catch (Exception $e) {
    print_r($e->getMessage());
}

a) Hierarchical structure of Schema attributes that can be used:

"id": "/Plan"
    "name"
    "interval"
    "repeats"

Para verificar mais detalhes, acesse aqui e explore em nosso Playground.

b) Attributes that can be used to create a transaction:

Attribute	Description	Required	Type
`name`	Plan's name of the subscription. Minimum of 1 character and maximum of 255 characters (String).	Yes	String
`interval`	Frequency of billing.Determines the interval, in months that the subscription charge should be generated. Enter 1 for monthly subscription. Example 1: if interval = 1 and repeats = null, will be generated 1 (one) charge per month, that is, the recurring charge will be monthly, according to the first due date chosen and generated indefinitely. Example 2: if interval = 6 and repeats = 2, 1 (one) charge will be generated every 6 (six) months, totaling 2 (two) charges in 12 months (one in the 6th month and another in the 12th month). Minimum 1 month and maximum 24 months.	Yes	Integer
`repeats`	How many charges should be generated. Determines the number of times the charge should be generated. If nothing is sent, the charge is generated indefinitely or until the plan is cancelled. Example 1: if interval = 1 and repeats = null, 1 (one) charge will be generated per month, that is, the recurring charge will be monthly, according to the first due date chosen. Example 2: if interval = 6 and repeats = 2, 1 (one) charge will be generated every 6 (six) months, totaling 2 (two) charges in 12 months (one in the 6th month and another in the 12th month). Default: Unlimited. Minimum of 2 and maximum of 120.	No	Integer

2. Create subscriptions to link to the plan

With the plan created, it's time to create subscriptions by associating them with plan(s). Subscriptions are applicable when you need to bill your customers on a recurring basis. In this way, subsequent costs will be created automatically based on the plan configuration.

It should be noted that the plan_id of the previously created plan to which you want to associate must be informed.

To associate subscriptions with plans, you must send a POST request to the /plan/:id/subscription route, where :id is the plan_id of the plan you want to link to the subscription.

If you want, you can explore and learn more about this feature using our Playground

The example below shows how this can be done, using the SDK's available:

<?php
 
require __DIR__.'/../../vendor/autoload.php'; // caminho relacionado a SDK
 
use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;
 
$clientId = 'informe_seu_client_id'; // insira seu Client_Id, conforme o ambiente (Des ou Prod)
$clientSecret = 'informe_seu_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod)
 
$options = [
  'client_id' => $clientId,
  'client_secret' => $clientSecret,
  'sandbox' => true // altere conforme o ambiente (true = desenvolvimento e false = producao)
];
 
$item_1 = [
    'name' => 'Item 1', // nome do item, produto ou serviço
    'amount' => 1, // quantidade
    'value' => 1000 // valor (1000 = R$ 10,00) (Obs: É possível a criação de itens com valores negativos. Porém, o valor total da fatura deve ser superior ao valor mínimo para geração de transações.)
];
 
$item_2 = [
    'name' => 'Item 2' // nome do item, produto ou serviço
    'amount' => 2, // quantidade
    'value' => 2000 // valor (2000 = R$ 20,00)
];
 
$items =  [
    $item_1,
    $item_2
];
// Exemplo para receber notificações da alteração do status da transação.
// $metadata = ['notification_url'=>'sua_url_de_notificacao_.com.br']
// Outros detalhes em: https://dev.gerencianet.com.br/docs/notificacoes

// Como enviar seu $body com o $metadata
// $body  =  [
//    'items' => $items,
//    'metadata' => $metadata
// ];

$body  =  [
    'items' => $items
];

// $plan_id refere-se ao ID do plano criado anteriormente

$params = [
  'id' => $plan_id
];
 
try {
    $api = new Gerencianet($options);
    $subscription = $api->createSubscription($params, $body);
 
    print_r($subscription);
} catch (GerencianetException $e) {
    print_r($e->code);
    print_r($e->error);
    print_r($e->errorDescription);
} catch (Exception $e) {
    print_r($e->getMessage());
}

a) Hierarchical structure of Schema attributes that can be used:

"id": "/Subscription"
    "items"
        "name"
        "value"
        "amount"
    "shippings"
        "name"
        "value"
        "payee_code"
    "metadata"
        "custom_id"
        "notification_url"

Para verificar mais detalhes, acesse aqui e explore em nosso Playground.

b) Attributes that can be used to associate a subscription with a plan:

Attribute	Description	Required	Type
`items`	item being sold. The same transaction can have unlimited items. Item attributes: `name`// Name of the item, product or service. Minimum 1 character and maximum 255 characters (String). `value`// Value, in cents. Ex: R$ 10.00 = 1000. Integer `amount`// Quantity. Integer	Yes	Array
`shippings`	Determines the shipping amount(s) for a transaction. The same transaction can have unlimited shipping values. Shipping attributes: `name`// Shipping label. Maximum 255 characters. String. `value`// Shipping value, in cents (1990 is equivalent to R$19.90). Integer	No	Array
`metadata`	Defines a transaction specific data Metadata attributes: `custom_id`// Allows you to associate a Gerencianet transaction with a specific ID on your system or application, allowing you to identify it if you have a specific identification and want to keep it. Maximum 255 characters. String/null. `notification_url`// Address of your valid URL that will receive transaction status change notifications. Maximum 255 characters. String/null.	No	Object

3. Define a subscription payment method and customer data

After creating the subscription plan and associating subscriptions to the plans, it is time to associate the recurring payment method for the subscriptions, which can be banking_billet (boleto) or credit_card ( credit card).

Credit Card: your customer makes the payment, according to the frequency you defined (monthly, quarterly, etc.) in the plan, the same amount being automatically charged to your customer's credit card. In the recurrence by card, your customer enters the card data only in the first payment, then the charge is carried out automatically without having to inform the data again;
Boleto Bancário: will be generated according to the number of repetitions defined by the plan, and can be sent by email. The subscriber or seller can unsubscribe at any time. When this occurs, the two are notified via email, with all the details of the cancellation.

"trial_days" attribute that allows granting a trial period

The API provides the trial_days attribute, which allows you to define a number of days for a free trial of the subscription plan. Attribute only available when payment is credit_card.

For details, see the table below: Objeto Credit_Card ("credit card)

To associate subscriptions with the payment method, you must send a POST request to the /subscription/:id/pay route, where :id is the subscription_id of the desired subscription .

If you want, you can explore and learn more about this feature using our Playground.

The example below shows how this can be done, using the SDK's available:

// Função paySubscription

// Forma de pagamento por boleto bancário ("banking_billet")

$params = ['id' => $subscription_id];

$customer = [
    'name' => 'Gorbadoc Oldbuck',
    'cpf' => '94271564656',
    'phone_number' => '5144916523'
];

$body = [
    'payment' => [
        'banking_billet' => [
            'expire_at' => '2018-12-12',
            'customer' => $customer
        ]
    ]
];

try {
    $api = new Gerencianet($options);
    $subscription = $api->paySubscription($params, $body);

    print_r($subscription);
} catch (GerencianetException $e) {
    print_r($e->code);
    print_r($e->error);
    print_r($e->errorDescription);
} catch (Exception $e) {
    print_r($e->getMessage());
}


// Forma de pagamento por cartão de crédito ("credit_card")

$params = ['id' => $subscription_id];

$paymentToken = 'payment_token';

$customer = [
    'name' => 'Gorbadoc Oldbuck',
    'cpf' => '94271564656',
    'phone_number' => '5144916523',
    'email' => 'oldbuck@gerencianet.com.br',
    'birth' => '1977-01-15'
];

$billingAddress = [
    'street' => 'Av. JK',
    'number' => 909,
    'neighborhood' => 'Bauxita',
    'zipcode' => '35400000',
    'city' => 'Ouro Preto',
    'state' => 'MG',
];

$body = [
    'payment' => [
        'credit_card' => [
            'billing_address' => $billingAddress,
            'payment_token' => $paymentToken,
            'customer' => $customer
        ]
    ]
];

try {
    $api = new Gerencianet($options);
    $subscription = $api->paySubscription($params, $body);

    print_r($subscription);
} catch (GerencianetException $e) {
    print_r($e->code);
    print_r($e->error);
    print_r($e->errorDescription);
} catch (Exception $e) {
    print_r($e->getMessage());
}

a) Hierarchical structure of Schema attributes that can be used:

"id": "/SubscriptionPay"
    "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"

Para verificar mais detalhes, acesse aqui e explore em nosso Playground.

b) Attributes that can be used to define the payment method for the subscription:

Attribute	Description	Required	Type
`payment`	Tag raiz	Yes	Object Payment

Object Payment

Attribute	Description	Required	Type
`banking_billet`	"boleto bancário" as a payment method.	Yes **	Object
`credit_card`	"credit card" as a payment method	Yes **	Object Credit_Card

The attribute with (* *) s related to the payment method and is mandatory and can be boleto bancário or credit card

Object Banking_Billet ("boleto bancário")

Attribute	Description	Required	Type
`name`	Nome do cliente. Mínimo de 1 caractere e máximo de 255 caracteres (String).	Yes Obs: Para Pessoa Jurídica não serão obrigatórios o nome e CPF, apenas os demais dados do cliente.	String
`cpf`	CPF válido do cliente (sem pontos, vírgulas ou hífen). Tamanho: 11 caracteres.	Yes Obs: Para Pessoa Jurídica não serão obrigatórios o nome e CPF, apenas os demais dados do cliente.	String
`email`	Email do cliente. Máximo de 255 caracteres. Ex.: email@email.com.	No	String
`phone_number`	Telefone do cliente. Formato: sem pontos ou vírgulas, com DDD de 2 caracteres (9º dígito é opcional). Ex.: 11988887777	Yes Obs: Para Pessoa Jurídica não serão obrigatórios o nome e CPF, apenas os demais dados do cliente.	String
`birth`	Data de nascimento do cliente. Formato: YYYY-MM-DD	No	String
`address`	Endereço do cliente. Atributos de address: `street`// Nome da rua (Object) `number`// Número (String/Integer) `neighborhood`// Bairro (String) `zipcode`// CEP (sem pontos ou hífen) (String) `city`// Cidade (String) `complement`// Complemento (String/null) `state`// Estado (2 caracteres) (Object)	No	Object
`juridical_person`	Dados de pessoa jurídica. Atributos de juridical_person: `corporate_name`// Nome da razão social. Mínimo de 1 caractere e máximo de 255. String. `cnpj`// CNPJ da empresa. Tamanho: 14 caracteres. String.	No	Object
`expire_at`	Data de vencimento do boleto. Formato: YYYY-MM-DD	Yes	String
`discount`	Define dados de desconto sobre a cobrança. Atributos de discount: type// Tipo do desconto (String). Valores permitidos: `currency`: o desconto será informado em centavos. `percentage`: o desconto será informado em porcentagem. `cnpj`// CNPJ da empresa. Tamanho: 14 caracteres. String. value*// Valor do desconto (Integer). Se o tipo do desconto for `currency` , o valor desta tag deverá ser informada pelo integrador em centavos (ou seja, 500 equivale a R$ 5,00). Caso o tipo do desconto seja `percentage`, o valor deverá ser multiplicado por 100 (ou seja, 1500 equivale a 15%). Exemplos: 1)`currency`// deve ser informado em centavos, ou seja, se o desconto será de R$ 5,99, o integrador deve informar `599`; 2)`percentage` // deve ser informado em centavos, ou seja, se o desconto é de 15%, o integrador deve informar `1500`.	No	Object
`conditional_discount`	Define desconto condicional que é válido até uma data específica. Se o pagamento não for efetuado até aquela data, o desconto é invalidado. Atributos de conditional_discount: type// Tipo do desconto (String). Valores permitidos: `currency`: o desconto será informado em centavos. `percentage`: o desconto será informado em porcentagem. `cnpj`// CNPJ da empresa. Tamanho: 14 caracteres. String. value// Valor do desconto (Integer). Se o tipo do desconto for `currency` , o valor desta tag deverá ser informada pelo integrador em centavos (ou seja, 500 equivale a R$ 5,00). Caso o tipo do desconto seja `percentage`, o valor deverá ser multiplicado por 100 (ou seja, 1500 equivale a 15%). Exemplos: 1)`currency`// deve ser informado em centavos, ou seja, se o desconto será de R$ 5,99, o integrador deve informar `599`; 2)`percentage` // deve ser informado em centavos, ou seja, se o desconto é de 15%, o integrador deve informar `1500`. until_date, // Data máxima que o desconto será concedido. (String). Formato: YYYY-MM-DD	No	Object
`configurations`	Permite incluir no boleto multa e juros caso seja pago após o vencimento. Atributos de configurations: fine// Valor cobrado de multa após o vencimento. Por exemplo: se você quiser 2%, você deve informar `200`.Mínimo de 0 e máximo de 1000. Integer. Caso você possua configurações de multa ativada na Gerencianet e queira gerar emissões na API sem multa, utilize `0`como valor do atributo `fine` interest// Valor cobrado de juros por dia após a data de vencimento. Por exemplo: se você quiser 0,033%, você deve informar `33`.Mínimo de 0 e máximo de 330. Integer. Caso você possua configurações de multa ativada na Gerencianet e queira gerar emissões na API sem juros, utilize `0` como valor do atributo `interest`	No	Object
`message`	Permite incluir no boleto uma "observação", ou em outras palavras, uma mensagem para o cliente. Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê. Até 4 linhas contendo 100 caracteres em cada linha. String. O operador `\n`é utilizado para efetuar a quebra de linha.	No	String

Object Credit_Card

Attribute	Description	Required	Type
`customer`	Dados pessoais do pagador. Atributos de customer: `name` // Nome (String) `cpf` // CPF do cliente (sem pontos, vírgulas ou hífen).(String) `email` // Endereço de email válido do cliente. (String) `phone_number` // Telefone válido do cliente, sem caracteres especiais. (String) `birth*` // Data de Nascimento do cliente (data válida em formato YYYY-MM-DD). (String) `address` // Endereço de Entrega. (Object) (mais informações) `juridical_person` // Dados de pessoa jurídica. (Object) (mais informações)	Yes	Object
`installments`	Número de parcelas em que o pagamento deve ser dividido. Mínimo 1 e máximo 12. Integer.	No	Integer
`discount`	Define dados de desconto sobre a cobrança. Atributos de discount: type// Tipo do desconto (String). Valores permitidos: `currency`: o desconto será informado em centavos. `percentage`: o desconto será informado em porcentagem. `cnpj`// CNPJ da empresa. Tamanho: 14 caracteres. String. value*// Valor do desconto (Integer). Se o tipo do desconto for `currency` , o valor desta tag deverá ser informada pelo integrador em centavos (ou seja, 500 equivale a R$ 5,00). Caso o tipo do desconto seja `percentage`, o valor deverá ser multiplicado por 100 (ou seja, 1500 equivale a 15%). Exemplos: 1)`currency`// deve ser informado em centavos, ou seja, se o desconto será de R$ 5,99, o integrador deve informar `599`; 2)`percentage` // deve ser informado em centavos, ou seja, se o desconto é de 15%, o integrador deve informar `1500`.	No	Object
`billing_address`	Endereço de cobrança (mais informações) Atributos de billing_address: `street`// Nome da rua (Object) `number`// Número (String/Integer) `neighborhood`// Bairro (String) `zipcode`// CEP (sem pontos ou hífen) (String) `city`// Cidade (String) `complement`// Complemento (String/null) `state`// Estado (2 caracteres) (Object)	No	Object
`payment_token`	Token único de pagamento obtido na primeira etapa da geração da transação.	Yes	String
`message`	Permite incluir na cobrança uma "observação", ou em outras palavras, uma mensagem para o cliente. Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê. Até 4 linhas contendo 100 caracteres em cada linha. String. O operador `\n`é utilizado para efetuar a quebra de linha.	No	String
`trial_days`	Permite definir uma quantidade de dias para teste gratuito do plano de assinatura. O período para a avaliação gratuita, definido em `trial_days`, começa a contar a partir do dia seguinte ao dia da realização da assinatura. Atributo disponível somente quando o pagamento for `credit_card`. Mínimo de 1 dia e máximo de 365 dias. Por exemplo: Criei um plano de assinatura em 25/09/2017 e defini `trial_days: 7` é utilizado para efetuar a quebra de linha. Isso significa que o primeiro pagamento será cobrado no dia 02/10/2017, e se for cancelado antes de 02/10/2017, então nada será cobrado.	No	Integer

Fields with * represent mandatory values

Payment made as a Juridical Person (PJ)

The customer associated with the subscription can be a Juridical Person. In this case, the Corporate Name and CNPJ of the paying company must be informed within the attribute juridical_person.

Juridical Person on how to generate a subscription (recurrence) for a client who is a Juridical Person (PJ).

List of all possible statuses of a subscription

All subscriptions have statuses, which represent the "situation" of that subscription. Therefore, it is important to know the possible statuses in the API to provide the proper handling in your system.

Check this link all details of possible subscription statuses.

API's subscription callbacks (notifications) for your system

:class: hyperlinkcolor Notifications let you know when a subscription changes status. In this way, you will be able to identify when the charge is paid, for example.

Check this link all the details on how to implement your notification URL.

4. Other endpoints and methods

There are other subscription's endpoints and methods (recurring billing) that are available in the API and can be exploited by the integrator. Check out the complete list:

5. Vídeo: Creating subscriptions (recurring billing)

Thinking of offering new ways of transmitting information, Gestoret makes the following video available in order to explain, in a clear and objective way, how to create a subscription plan and associate it with the payment method (credit card or boleto) to charge your customer recurrently.

5.1. Creating subscriptions (recurring billing) through the Gerencianet integration AP

Complete Course on Integration with the Gerencianet API

For access to other classes, on other subjects, access the page Integrations Online Course .

6. Next steps

With the subscriptions created, it is important to know all the endpoints that can be used. Also, if you have any doubts about the subscription mechanism, see how it works.

Create subscription

Bolix

1. Create a subscription plan

a) Hierarchical structure of Schema attributes that can be used:

b) Attributes that can be used to create a transaction:

2. Create subscriptions to link to the plan

a) Hierarchical structure of Schema attributes that can be used:

b) Attributes that can be used to associate a subscription with a plan:

3. Define a subscription payment method and customer data

"trial_days" attribute that allows granting a trial period

a) Hierarchical structure of Schema attributes that can be used:

b) Attributes that can be used to define the payment method for the subscription:

Payment made as a Juridical Person (PJ)

List of all possible statuses of a subscription

API's subscription callbacks (notifications) for your system

4. Other endpoints and methods

5. Vídeo: Creating subscriptions (recurring billing)

5.1. Creating subscriptions (recurring billing) through the Gerencianet integration AP

Complete Course on Integration with the Gerencianet API

6. Next steps

NEED HELP?

FIND OUT MORE

UTILITIES

Acompanhe-nos

Create subscription

Bolix

1. Create a subscription plan#

a) Hierarchical structure of Schema attributes that can be used:#

b) Attributes that can be used to create a transaction:#

2. Create subscriptions to link to the plan#

a) Hierarchical structure of Schema attributes that can be used:#

b) Attributes that can be used to associate a subscription with a plan:#

3. Define a subscription payment method and customer data#

"trial_days" attribute that allows granting a trial period

a) Hierarchical structure of Schema attributes that can be used:#

b) Attributes that can be used to define the payment method for the subscription:#

Payment made as a Juridical Person (PJ)

List of all possible statuses of a subscription

API's subscription callbacks (notifications) for your system

4. Other endpoints and methods#

5. Vídeo: Creating subscriptions (recurring billing)#

5.1. Creating subscriptions (recurring billing) through the Gerencianet integration AP#

Complete Course on Integration with the Gerencianet API

6. Next steps#

1. Create a subscription plan

a) Hierarchical structure of Schema attributes that can be used:

b) Attributes that can be used to create a transaction:

2. Create subscriptions to link to the plan

a) Hierarchical structure of Schema attributes that can be used:

b) Attributes that can be used to associate a subscription with a plan:

3. Define a subscription payment method and customer data

a) Hierarchical structure of Schema attributes that can be used:

b) Attributes that can be used to define the payment method for the subscription:

4. Other endpoints and methods

5. Vídeo: Creating subscriptions (recurring billing)

5.1. Creating subscriptions (recurring billing) through the Gerencianet integration AP

6. Next steps