Creating payment link

Learn how to create a link to a Gerencianet payment screen for your customers to make payments. To create it is very simple and requires only two steps:

  1. First, create the transaction, informing the item/product/service, value, quantity, etc;

  2. Now to create payment link, inform the charge_id of the transaction created earlier.

The rest of this page has the detailed procedures, 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 Gerencianet account, the charges generated by our module/plugin will already come with the pix on the ticket. More details about Bolix and how to activate it, click here.


1. Create the transaction

First, we need to generate the transaction (also called "charge"). It is at this moment that the name of the item/product/service, transaction value, quantity, among other possible information will be informed.

After creating it, the charge_id will be returned, which is the unique identifier of the transaction and will be used to associate the payment method.

As soon as this transaction is created, it receives the status new, which means that the charge has been generated and is awaiting definition of the payment method. This charge will only change its status when the integrator defines your payment method.

To generate a transaction, you must send a POST request to the /v1/charge 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)
];
$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']
// Como enviar seu $body com o $metadata
// $body = [
// 'items' => $items,
// 'metadata' => $metadata
// ];
$body = [
'items' => $items
];
try {
$api = new Gerencianet($options);
$charge = $api->createCharge([], $body);
print_r($charge);
} 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": "/Charge"
"items"
"name"
"value"
"amount"
"marketplace"
"payee_code"
"percentage"
"shippings"
"name"
"value"
"payee_code"
"metadata"
"custom_id"
"notification_url"

To check more details, go here and explore in our Playground.


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

Objeto items

AttributeDescriptionMandatoryType
itemsitem being sold. The same transaction can have unlimited items.

Item attributes:
name*// Name of the item, product or service. Minimum of 1 character and maximum of 255 characters (String).

value*// Value, in cents. Ex: R$ 10,00 = 1000. Integer

amount Integer		YesArray
shippingsDetermines the shipping amount(s) for a transaction. The same transaction can have unlimited shipping values.

Shipping attributes:
name*// Rótulo do frete. Maximum of 255 characters. String.

value*// Freight value, in cents (1990 is equivalent to R$19.90). Integer		NoArray
metadataDefine transaction-specific data

Metadata attributes:
custom_id// It allows associating a Gerencianet transaction with a specific ID of your system or application, allowing you to identify it if you have a specific ID and want to keep it. Maximum of 255 characters. String/null.

notification_url// Address of your valid URL that will receive transaction status change notifications. Maximum of 255 characters. String/null.		NoObject

Fields with * represent mandatory values Now that the transaction has been created and you already have the charge_id, you need to associate it to get the payment link.


2. Creating a payment link

To create a payment link you need to have generated the transaction, that is, that you already have the charge identifier charge_id, as you will need to inform it.

Then simply send a POST request to the /v1/charge/:id/link route to generate a payment link, where the :id corresponds to the charge_id of the transaction created.

If you want, you can explore and learn more about this resource 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)
];
// $charge_id refere-se ao ID da transação gerada anteriormente
$params = [
'id' => $charge_id
];
$body = [
'billet_discount' => 5000, // desconto, em reais, caso o pagador escolha boleto (5000 equivale a R$ 50,00)
'card_discount' => 3000, // desconto, em reais, caso o pagador escolha cartão (3000 equivale a R$ 30,00)
'message' => '', // mensagem para o pagador com até 80 caracteres
'expire_at' => '2022-12-20', // data de vencimento da tela de pagamento e do próprio boleto
'request_delivery_address' => false, // solicitar endereço de entrega do comprador?
'payment_method' => 'all' // formas de pagamento disponíveis
];
try {
$api = new Gerencianet($options);
$response = $api->linkCharge($params, $body);
print_r($response);
} catch (GerencianetException $e) {
print_r($e->code);
print_r($e->error);
print_r($e->errorDescription);
} catch (Exception $e) {
print_r($e->getMessage());
}

important

To create a "payment link" (chargeLink), a previously created "transaction" (createCharge) must be informed. Therefore, if there is an attempt to pay and, for some reason, the payment confirmation is not successful (ex: card declined, customer wants to pay in another way, etc.), a new transaction must be generated and associated with a new payment, as the previous transaction will be in a waiting or unpaid status, which means that due to the payment attempt, it has already been linked to a payment method.


a) Attributes that can be used to create a payment link:

AttributeDescriptionMandatoryType
billet_discountDefines a discount, in reais, if the payer chooses a boleto bancário as the payment method (inform the entire amount, in reais).
5000 is equivalent to R$ 50,00		NoInteger
card_discountDefines a discount, in reais, if the payer chooses a credit card as the payment method (enter Integer value).
5000 equals to R$ 50,00		NoInteger
conditional_discountDefines conditional discount that is valid until a specific date. If payment is not made by that date, the discount is invalidated.

Conditional discount attributes:

type*// Discount type (String). Allowed values:
currency: the discount will be reported in cents.
percentage:the discount will be informed in percentage.

cnpj* Size: 14 characters. String.

value*// discount amount (Integer). If the discount type is currency , the value of this tag must be informed by the integrator in cents (ie 500 is equivalent to R$ 5.00). If the discount type is percentage, the value must be multiplied by 100 (ie 1500 equals 15%). Examples:
1)currency// must be informed in cents, that is, if the discount will be R$ 5.99, the integrator must inform 599;
2)percentage // must be informed in cents, that is, if the discount is 15%, the integrator must inform 1500.

until_date*, // Maximum date the discount will be granted. (String).
Format: YYYY-MM-DD		NoObject
messageDefines a message for the payer. The message appears on the payment screen, in the billing-related emails and on the boleto, if this is the chosen payment method.
Minimum of 3 and maximum of 80 characters.		NoString
expire_atDefines the due date of the payment screen and of the ticket itself, if this is the chosen payment method.
Format: YYYY-MM-DD		YesString
request_delivery_addressDefines whether the payment screen should ask the payer to enter a delivery address. There are two possible values:

  • true
  • false
YesBoolean
payment_methodDefines the payment methods that must be available on the screen for your customer to choose, which can be:

  • banking_billet (boleto bancário)
  • credit_card (cartão de crédito)
  • all (allow payment via boleto and card)
YesObject

Fields with * represent mandatory values


When consuming the /charge/:id/link endpoint, or through the Playground, the charge gains link status. In this way, the integrator can distinguish common charges that have not yet had a defined payment method (status new) from charges that have been associated with a payment link (status link).

The integrator only needs to redirect the payer to the link returned in the payment_url tag and everything else will be done on the Gerencianet payment screen.

Then, through the "Input Data" tab, a simple JSON that can be used to create the payment link. Also, you can see the predicted output and validation schema with all tags (mandatory and optional) available for this method. Remembering that you also need to inform the charge_id input parameter of the transaction created:

{
"message": "Write here, if you want, a message to your customer, limit of 80 characters",
"payment_method": "all",
"expire_at": "2022-12-20",
"request_delivery_address": false,
"billet_discount": 5000,
"card_discount": 3000
}

This JSON, present in the "Input Data" tab, defines the following information when creating the payment link:

  • message: defines a message to the payer. The message appears on the payment screen, in the billing-related emails and on the payment slip, if this is the chosen payment method (maximum 80 characters);
  • payment_method: defines the payment methods that must be available on the screen (banking_billet, credit_card ou all);
  • expire_at: defines the payment methods that must be available on the screen
  • request_delivery_address: defines whether the payment screen should ask the payer to enter a delivery address (true ou false);
  • billet_discount: defines a discount, in cents, if the payer chooses a bank slip as the payment method (enter Integer value);
  • card_discount: defines a discount, in cents, if the payer chooses a credit card as the payment method (enter Integer value).

List of all possible statuses of a transaction

All transactions have status, which represents the "status" of that transaction. Therefore, it is important to know the possible statuses in the API to provide the proper handling in your system.

Check out this link all the details of the possible status of the transactions.


API transaction callbacks (notifications) to your system

Notifications allow you to be informed when a transaction has changed status. In this way, you will be able to identify when a charge is paid, for example.

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


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

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

For more details, click here and explore in our Playground.

c) Customizing your payment screen:

You can set a color and logo for your screen. For that, Log into your Gerencianet account and access the menu Minha Conta > Tela de Pagamento.

Even if you prefer to use your own screen, the information defined here will also be used in emails triggered by the API. So we recommend that you do the customization anyway.

d) Testing in test environment (Playground):

To create a payment link, you must first create a charge in the API, consuming the POST /v1/charge endpoint. This endpoint returns, among other information, an identifier for the charge. The initial status of a charge is new:

{
"message": "Write here, if you want, a message to your customer, limit of 80 characters",
"payment_method": "all",
"expire_at": "2022-12-20",
"request_delivery_address": false,
"billet_discount": 5000,
"card_discount": 3000
}

Just below, the expected output data according to the input made above:

{
"code":200,
"data":{
"charge_id":121062,
"status":"new",
"total":1000,
"custom_id":null,
"created_at":"2022-10-31 10:43:57"
}
}

Knowing the charge identifier, just consume the POST endpoint /v1/charge/:id/link to generate a payment link.


3. Other endpoints and methods

There are other payment link related endpoints and methods that are available in the API and can be exploited by the integrator. Check out the complete list:


4. Video: Creating transaction via Playground (test environment/sandbox)

Thinking about offering new ways of transmitting information, Gerencianet makes the following video available in order to explain, in a clear and objective way, how to create a transaction via playground (sandbox).



Complete Course on Integration with the Gerencianet API

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