Splitting receipts

The marketplace is a tool that allows the division of an amount received between one or more people, according to the percentage defined at the time of creation of the charge.

When generating a transaction, it is possible to define the division of the amount between several Gerencianet accounts. We use the term "Marketplace Transaction" whenever the payment of a transaction implies partial or full transfers to other Gerencianet accounts. To issue, it is very simple and we provide two ways to carry out the issue:

Creating a Marketplace transaction in One Step, where the title is created in a single step.
Creating a Marketplace transaction in Two Steps, where the title is first created and then the payer and payment method are assigned.

Bolix

If you have activated Bolix in your Gestornet 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. Creating a Marketplace transaction in One Step

In this option, it is necessary that the body of the request contains all the minimum attributes required for issuing the title. Below are implementation examples using the available SDK's:

Important

For the creation of transactions via One Step to occur, it is normally necessary to update your SDK. All the files necessary for this are available through our repository and in our documentation.

<?php

require __DIR__.'/../../autoload.php';

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)
    ];

     $repass_1 = [
      'payee_code' => "Insira_aqui_o_indentificador_da_conta_destino", // identificador da conta Gerencianet (repasse 1)
      'percentage' => 2500 // porcentagem de repasse (2500 = 25%)
    ];
     
    $repass_2 = [
      'payee_code' => "Insira_aqui_o_indentificador_da_conta_destino", // identificador da conta Gerencianet (repasse 2)
      'percentage' => 1500 // porcentagem de repasse (1500 = 15%)
    ];
     
    $repasses = [
      $repass_1,
      $repass_2
    ];

   $item_1 = [
       'name' => 'Item 1', // nome do item, produto ou serviço
       'amount' => 1, // quantidade
       'value' => 1500, // 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.)
       'marketplace'=>array('repasses'=>$repasses)
   ];
   $items = [
       $item_1
   ];
  $metadata = array('notification_url'=>'sua_url_de_notificacao_.com.br'); //Url de notificações
   $customer = [
       'name' => 'Gorbadoc Oldbuck', // nome do cliente
       'cpf' => '94271564656', // cpf válido do cliente
       'phone_number' => '5144916523', // telefone do cliente
   ];
   $discount = [ // configuração de descontos
       'type' => 'currency', // tipo de desconto a ser aplicado
       'value' => 599 // valor de desconto 
   ];
   $configurations = [ // configurações de juros e mora
       'fine' => 200, // porcentagem de multa
       'interest' => 33 // porcentagem de juros
   ];
   $conditional_discount = [ // configurações de desconto condicional
       'type' => 'percentage', // seleção do tipo de desconto 
       'value' => 500, // porcentagem de desconto
       'until_date' => '2022-09-13' // data máxima para aplicação do desconto
   ];
   $bankingBillet = [
       'expire_at' => '2022-09-13', // data de vencimento do titulo
       'message' => 'teste\nteste\nteste\nteste', // mensagem a ser exibida no boleto
       'customer' => $customer,
       'discount' =>$discount,
       'conditional_discount' => $conditional_discount
   ];
   $payment = [
       'banking_billet' => $bankingBillet // forma de pagamento (banking_billet = boleto)
   ];
   $body = [
       'items' => $items,
       'metadata' =>$metadata,
       'payment' => $payment
   ];
   try {
     $api = new Gerencianet($options);
     $pay_charge = $api->oneStep([],$body);
     echo '<pre>';
     print_r($pay_charge);
     echo '<pre>';
     
    } 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:

"OneStep": "/Charge/one-step"
    "items"
        "name"
        "value"
        "amount"
        "marketplace"
            "payee_code"
            "percentage"
    "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"

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

Object items

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 (default: 1) `marketplace`// Refers to the transfer settings. Attributes: `payee_code` // Gerencianet's account identifier code, unique per account - check (código identificador da conta Gerencianet) (String) `percentage*`(percentage of transfer, 9000 is equivalent to 90%) . 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 transaction-specific data Metadata attributes: `custom_id`// Allows you to associate a Gestornet 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

Fields with * represent mandatory values

Objeto Payment

Attribute	Description	Required	Type
`banking_billet`	Payment method via "boleto bancário"	Yes	Objeto

Object Banking_Billet

Attribute	Description	Required	Type
`name`	Customer's name Minimum of 1 character and maximum of 255 characters (String).	Yes Obs: For Juridical Person, the name and CPF will not be mandatory, only the other customer data.	String
`cpf`	Valid customer ID (no dots, commas or hyphens). Size: 11 characters.	Yes Obs: For Juridical Person, the name and CPF will not be mandatory, only the other customer data.	String
`email`	Customer's email. Maximum of 255 characters. Ex.: email@email.com	No	String
`phone_number`	Customer's phome number. Format: without periods or commas, with 2-character area code (9th digit is optional). Ex.: 11988887777	Yes	String
`birth`	Customer's date of birth. Format: YYYY-MM-DD	No	String
`address`	Customer address. Address attributes: `street`// Street name (Object) `number`// House number (String/Integer) `neighborhood` (String) `zipcode`// CEP (no dots or hyphen, 8 characters) (String) `city`// City (String) `complement` (String/null) `state`// State (2 characters) (Object)	No	Object
`juridical_person`	Juridical person data. Attributes of juridical_person: `corporate_name`Minimum of 1 character and maximum of 255. String. `cnpj`// CNPJ of the company. Size: 14 characters. String.	No	Object
`expire_at`	Charge's expiration date. Format: YYYY-MM-DD	Yes	String
`discount`	Defines discount data about the charge. Discount attributes: type* // Type of discount (String). Allowed values: `currency`: the discount will be reported in cents. `percentage`: the discount will be informed in percentage. `cnpj`// CNPJ of the company. Size: 14 characters. String. value// Discount value (Integer). If the discount type is `currency` , the value of this tag must be informed by the integrator in cents (500 is equivalent to R$ 5.00). If the discount type is `percentage`, the value must be multiplied by 100 ( 1500 is equivalent to 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` .	No	Object
`conditional_discount`	Defines conditional discount that is valid until a specific date. If payment is not made by that date, the discount is invalidated. Attributes of conditional_discount: type// Discount type (String). Allowed values: `currency`: the discount will be reported in cents. `percentage`: the discount will be informed in percentage. `cnpj`// CNPJ of the company. Size: 14 characters. String. value// Discount value (Integer). If the discount type is `currency` , the value of this tag must be informed by the integrator in cents (500 is equivalent to R$ 5.00). If the discount type is `percentage`, the value must be multiplied by 100 (1500 is equivalent to 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	No	Object
`configurations`	Allows you to include a fine and interest in the charge if it is paid after the due date. Configuration attributes: fine// Amount charged for fine after expiration. For example: if you want 2%, you would enter `200`.Minimum of 0 and maximum of 1000. Integer. If you have fine settings enabled in Gerencianet and want to generate API emissions without fines, use `0` as the value of the `fine` attribute interest// Amount charged for interest per day after the due date. For example: if you want 0.033%, you would enter `33`.Minimum of 0 and maximum of 330. Integer. If you have fine settings activated in Gestoret and want to generate interest-free API issues, use `0` as the value of the `interest attribute`	No	Object
`message`	Allows you to include an "observation" in the charge, or in other words, a message for the customer. This message can be seen in e-mails related to billing, on the payment via boleto or carnÊ. Up to 4 lines containing 100 characters in each line. String. The `\n` operator is used to perform the line break .	No	String

Fields with * represent mandatory values

2. Creating a Marketplace transaction in Two Steps

To create a Marketplace transaction by the traditional method, it is necessary to follow the steps listed below:

2.1. Create marketplace transaction, informing transfer account(s), item/product/service, value, quantity, etc;

2.2. Associate with the desired payment method, informing the transaction's charge_id and the paying customer's data.

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 .

2.1 Creating a Marketplace transaction

Transactions that have at least one item defined as a marketplace item or shipping amounts destined for accounts other than the integrating account are considered "Marketplace Transactions". With the Gerencianet marketplace it is possible for the amount paid by the end customer to be automatically divided between seller and supplier, without the process having to be carried out manually.

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

An important observation is that the Gerencianet intermediation tax is charged proportionally to all accounts that receive the transfers, therefore, all those involved need a Gerencianet account.

The code below exemplifies the use of transfers, in which the total amount of the transaction is R$ 50.00. According to the code below, the amount will be divided between 3 (three) Gerencianet accounts. The first account will have 25% of the value, the second account will have 15% of the value and the third account will have the remainder, which in this case is 60% of the value.

The payee_code attribute refers to the Gerencianet "account identifier" and will be used to identify the accounts that will receive the transfers. Check out where to find it on your platform (veja onde localizar).

If you want, you can explore and learn more about this feature (using our Playground)[../AmbienteTestes/PlaygroundTransacoes#post-v1charge].

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)
];
 
$repass_1 = [
  'payee_code' => "informe_payee_code_conta", // identificador da conta Gerencianet (repasse 1)
  'percentage' => 2500 // porcentagem de repasse (2500 = 25%)
];
 
$repass_2 = [
  'payee_code' => "informe_payee_code_conta", // identificador da conta Gerencianet (repasse 2)
  'percentage' => 1500 // porcentagem de repasse (1500 = 15%)
];
 
$repasses = [
  $repass_1,
  $repass_2
];
 
$item_1 = [
    'name' => 'Meu Produto', // nome do item, produto ou serviço
    'amount' => 1, // quantidade
    'value' => 5000, // valor (5000 = R$ 50,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.)
    'marketplace'=>array('repasses'=>$repasses)
];
 
$items =  [
    $item_1
];
 
// 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"

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
`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 (default: 1) `marketplace`// Refers to the transfer settings. Attributes: `payee_code` // Manager account identifier code, unique per account - check (código identificador da conta Gerencianet) (String) `percentage*`(percentage of transfer, with 9000 being equivalent to 90%).Integer	Yes	Array
`shippings`	Determina o(s) valor(es) de frete(s) de uma transação. Uma mesma transação pode possuir ilimitados valores de frete. Atributos de shippings: `name`// Rótulo do frete. Máximo de 255 caracteres. String. `value`// Valor do frete, em centavos (1990 equivale a R$19,90). Integer	No	Array
`metadata`	Defines 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

Fields with * represent mandatory values

2.2. Associate with the payment method via boleto or card

After creating the marketplace transaction, you will receive the charge_id. It will be used for you to define the payment method for that transaction.

For details, access the page referring to the form you want: boleto bancário and credit card.

3. Videos: Marketplace

Thinking about offering new ways of transmitting information, Gerencianet makes available the following videos in order to explain, in a clear and objective way, how to create a marketplace transaction through integration with the Gestoret API.

3.1.Overview - Getting to Know the Marketplace (Gerencianet API integration)

3.2. Creating transaction via Marketplace (Gerencianet API integration)

Complete Course on Integration with the Gerencianet's API

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

4. Next steps

Let's get to know more about the details of the marketplace's working mechanism?

Splitting receipts

Bolix

1. Creating a Marketplace transaction in One Step

Important

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

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

2. Creating a Marketplace transaction in Two Steps

2.1 Creating a Marketplace transaction

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

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

2.2. Associate with the payment method via boleto or card

3. Videos: Marketplace

3.1.Overview - Getting to Know the Marketplace (Gerencianet API integration)

3.2. Creating transaction via Marketplace (Gerencianet API integration)

Complete Course on Integration with the Gerencianet's API

4. Next steps

NEED HELP?

FIND OUT MORE

UTILITIES

Acompanhe-nos

Splitting receipts

Bolix

1. Creating a Marketplace transaction in One Step#

Important

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

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

2. Creating a Marketplace transaction in Two Steps#

2.1 Creating a Marketplace transaction#

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

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

2.2. Associate with the payment method via boleto or card#

3. Videos: Marketplace#

3.1.Overview - Getting to Know the Marketplace (Gerencianet API integration)#

3.2. Creating transaction via Marketplace (Gerencianet API integration)#

Complete Course on Integration with the Gerencianet's API

4. Next steps#

1. Creating a Marketplace transaction in One Step

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

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

2. Creating a Marketplace transaction in Two Steps

2.1 Creating a Marketplace transaction

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

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

2.2. Associate with the payment method via boleto or card

3. Videos: Marketplace

3.1.Overview - Getting to Know the Marketplace (Gerencianet API integration)

3.2. Creating transaction via Marketplace (Gerencianet API integration)

4. Next steps