Passo a passo para gerar uma cobrança com a configuração de split de pagamento na API Efí
Introdução
Importante! O Split de pagamento só pode ser realizado entre contas Efí, sem limite máximo de contas para o repasse.
O Split de pagamento da Efí pode ser usado em situações em que o valor pago pelo comprador deve ser dividido entre dois ou mais vendedores, conforme porcentagem ou valor fixo definido no momento de criação da cobrança.
O conceito de Split de pagamento é simples. É um ambiente de varejo online onde diversos lojistas ofertam seus produtos em um único local. Imagine como um shopping virtual, onde várias lojas se reúnem para vender diferentes produtos e serviços, oferecendo uma variedade maior de opções aos clientes.
Com o Split de pagamento Efí, qualquer conta Efí pode criar sua própria plataforma de vendas com múltiplos vendedores. Com essa solução, você pode usar o seu site para realizar as vendas e, por meio da integração, definir como o valor recebido será dividido entre as diferentes contas Efí. Isso funciona tanto para a sua conta quanto para a de seus parceiros, permitindo uma experiência de compras mais completa e integrada.
Como funciona
Se um item de uma transação for marcado como item de Split de pagamento, todos os itens serão considerados itens de Split de pagamento;
O integrador tem a flexibilidade de configurar o split, optando entre divisão por porcentagem ou por um valor fixo. Em configurações de repasse por porcentagem
, a taxa de intermediação da Efí pode ser configurada em duas modalidades: mode = 1
para que a tarifa seja descontada apenas da conta principal que emitiu a cobrança, e mode = 2
para que a tarifa seja descontada proporcionalmente ao percentual definido para cada conta que receberá o repasse. Caso o atributo mode
não seja informado na requisição, o padrão será mode = 2
.
Em configurações de repasse com valor fixo
, a tarifa deverá ser obrigatoriamente descontada apenas da conta principal que gerou a cobrança. Portanto, o integrador deve especificar mode = 1
.
Ao utilizar a divisão por porcentagem, se o total de repasses de um item for inferior a 100%, o restante será automaticamente repassado para a conta integradora e se o total de repasses de um item for superior a 100%, a transação não poderá ser gerada;
Ao utilizar a divisão por valor fixo, se o total de repasses de um item for inferior ao valor total da cobrança, o valor restante será automaticamente repassado para a conta integradora e se o total de repasses de um item for superior ao valor total da cobrança, a transação não poderá ser gerada;
Os repasses do Split de pagamento são realizados individualmente para cada produto da cobrança. Cada produto pode ter repasses para contas diferentes na mesma cobrança;
Não é possível fazer um repasse parcial do valor do envio;
Para que o Split de pagamento funcione, o único dado necessário é o identificador de conta ("payee_code") das contas que receberão os repasses;
Os repasses não podem ter um valor igual a zero por cento;
É possível gerar cobranças com vários itens, alguns com configuração Split de pagamento e outros sem;
Não é possível fazer dois repasses para a mesma conta no mesmo item;
É permitido ter repasses de valores diferentes ou iguais para a mesma conta em itens diferentes da mesma transação.
Configurações do Split de pagamento
Descrição dos atributos para configurar o Split de pagamento
Criação de transação Split de pagamento em One Step (Um passo)
Nesta opção, é necessário que o body da requisição contenha todos os atributos mínimos obrigatórios para a emissão do titulo.
Essa opção permite criar uma transação e associar um método de pagamento (boleto bancário ou cartão de crédito) em apenas uma etapa
Importante! Para que a criação de transações via One Step ocorra sem problemas, é necessário atualizar sua SDK. Todos os arquivos necessários para isso estão disponíveis em nosso repositório e na documentação.
Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
"items"
"name"
"value"
"amount"
"marketplace"
"mode"
"repasses"
"payee_code"
"percentage"
"fixed"
"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"
"days_to_write_off"
"fine"
"interest"
"value"
"type"
"message"
POST /v1/charge/one-step
Requer ativação da API de Emissão de cobranças
em sua aplicação
Requisição
- Split de pagamento - porcentagem (Boleto)
- Split de pagamento - fixo (Boleto)
- Split de pagamento (Cartão)
{
"items": [
{
"name": "Meu Produto",
"value": 5990,
"amount": 1,
"marketplace": {
"repasses": [
{
"payee_code": "payee_code1",
"percentage": 2500
},
{
"payee_code": "payee_code2",
"percentage": 1500
}
]
}
}
],
"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-15",
"configurations": {
"fine": 200,
"interest": 33
},
"message": "Usando o atributo message, este conteúdo é exibido no campo OBSERVAÇÃO da cobrança emitida via API
e também no campo OBSERVAÇÃO DO VENDEDOR nos e-mails de cobrança enviados ao cliente
É possível utilizar até 4 linhas de conteúdo, com no máximo 100 caracteres por linha
Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê"
}
}
}
{
"items": [
{
"name": "Meu Produto",
"value": 5990,
"amount": 1,
"marketplace": {
"repasses": [
{
"payee_code": "payee_code1",
"fixed": 2500
},
{
"payee_code": "payee_code2",
"fixed": 1500
}
]
}
}
],
"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-15",
"configurations": {
"fine": 200,
"interest": 33
},
"message": "Usando o atributo message, este conteúdo é exibido no campo OBSERVAÇÃO da cobrança emitida via API
e também no campo OBSERVAÇÃO DO VENDEDOR nos e-mails de cobrança enviados ao cliente
É possível utilizar até 4 linhas de conteúdo, com no máximo 100 caracteres por linha
Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê"
}
}
}
{
"items": [
{
"name": "Meu Produto",
"value": 5990,
"amount": 1,
"marketplace": {
"repasses": [
{
"payee_code": "payee_code1",
"percentage": 2500
},
{
"payee_code": "payee_code2",
"percentage": 1500
}
]
}
}
],
"payment": {
"credit_card": {
"customer": {
"name": "Gorbadoc Oldbuck",
"cpf": "94271564656",
"email": "[email protected]",
"birth": "1990-08-29",
"phone_number": "5144916523"
},
"installments": 1,
"payment_token": "",
"billing_address": {
"street": "Avenida Juscelino Kubitschek",
"number": "909",
"neighborhood": "Bauxita",
"zipcode": "35400000",
"city": "Ouro Preto",
"complement": "",
"state": "MG"
}
}
}
}
Respostas As respostas abaixo representam Sucesso do consumo.
- 🟢 200 (Bolix)
- 🟢 200 (Boleto tradicional)
{
"code": 200,
"data": {
"barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000",
"pix":{
"qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1",
"qrcode_image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmc vMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..."
},
"link": "link_https_para_acesso_o_bolix",
"billet_link":"link_https_para_acesso_o_bolix",
"pdf": {
"charge": "link_https_do_pdf_da_cobranca"
},
"expire_at": "2023-12-15",
"charge_id": numero_charge_id,
"status": "waiting",
"total": 5990,
"payment": "banking_billet"
}
}
{
"code": 200,
"data": {
"barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000",
"link": "link_https_para_acesso_o_boleto",
"billet_link":"link_https_para_acesso_o_boleto",
"pdf": {
"charge": "link_https_do_pdf_da_cobranca"
},
"expire_at": "2023-12-15",
"charge_id": numero_charge_id,
"status": "waiting",
"total": 5990,
"payment": "banking_billet"
}
}
Criação de transação Split de pagamento em Two Steps (Dois passos)
- Crie a transação, informando conta(s) de repasse, o item/produto/serviço, valor, quantidade, etc;
- Associe a forma de pagamento desejado, informando o
charge_id
da transação e os dados do cliente pagador.
O restante desta página apresenta os procedimentos detalhados, mas lembre-se de instalar uma de nossas bibliotecas em seu servidor para executar os códigos de exemplo. Certifique-se de que a SDK da Efí foi instalada.
1. Criar transação
Transações com pelo menos um item definido como 'item de Split de pagamento' ou valores de fretes destinados a contas diferentes da conta integradora são chamadas de 'Transações de Split de pagamento'. Com o Split de pagamento da Efí, é possível dividir automaticamente o valor pago pelo cliente final entre o vendedor e o fornecedor, sem precisar fazer isso manualmente.
Para começar, precisamos gerar a transação, informando as contas da Efí para repasse, o nome do item/produto/serviço, o valor da transação, a quantidade e outras informações relevantes.
É importante notar que a taxa de intermediação da Efí pode ser configurada de duas formas: mode = 1
, para que a tarifa seja descontada apenas da conta que emitiu a cobrança, ou mode = 2
para que a tarifa seja descontada proporcionalmente ao percentual definido para todas as contas que receberão os repasses. Caso o atributo mode
não seja informado na requisição, será definido como padrão mode = 2
.
No exemplo abaixo, mostramos como usar os repasses em uma transação de R$ 50,00. De acordo com o código, o valor será dividido entre 3 contas Efí. A primeira conta receberá 25% do valor, a segunda conta receberá 15% e a terceira receberá o restante, que neste caso é 60% do valor.
O atributo payee_code
é o 'identificador de conta' Efí e será usado para identificar as contas que receberão os repasses. Você pode encontrar esse identificador em sua plataforma a (veja onde localizar).
POST /v1/charge
Requer ativação da API de Emissão de cobranças
em sua aplicação
Requisição
- Dados de entrada - porcentagem
- Dados de entrada - fixo
{
"items": [
{
"name": "Meu Produto",
"value": 5990,
"amount": 1,
"marketplace": {
"repasses": [
{
"payee_code": "payee_code1",
"percentage": 2500
},
{
"payee_code": "payee_code2",
"percentage": 1500
}
]
}
}
]
}
{
"items": [
{
"name": "Meu Produto",
"value": 5990,
"amount": 1,
"marketplace": {
"repasses": [
{
"payee_code": "payee_code1",
"fixed": 2500
},
{
"payee_code": "payee_code2",
"fixed": 1500
}
]
}
}
]
}
Respostas As respostas abaixo representam Sucesso do consumo.
{
"code": 200,
"data": {
"charge_id": numero_charge_id,
"status": "new",
"total": 8900,
"custom_id": null,
"created_at": "2021-06-01 14:58:46"
}
}
Após criar a transação de Split de pagamento, você receberá o charge_id
. Esse identificador será utilizado para que você escolha qual forma de pagamento deseja utilizar para essa transação.
POST /v1/charge/:id/pay
Requer ativação da API de Emissão de cobranças
em sua aplicação
Requisição
- Exemplo Boleto
- Exemplo Cartã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"
}
}
}
{
"payment": {
"credit_card": {
"customer": {
"name": "Gorbadoc Oldbuck",
"cpf": "94271564656",
"email": "[email protected]",
"birth": "1990-08-29",
"phone_number": "5144916523"
},
"installments": 1,
"payment_token": "",
"billing_address": {
"street": "Avenida Juscelino Kubitschek",
"number": "909",
"neighborhood": "Bauxita",
"zipcode": "35400000",
"city": "Ouro Preto",
"complement": "",
"state": "MG"
}
}
}
}
Respostas As respostas abaixo representam Sucesso do consumo.
- 🟢 200 (Bolix)
- 🟢 200 (Boleto tradicional)
{
"code": 200,
"data": {
"barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000",
"pix":{
"qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1",
"qrcode_image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmc vMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..."
},
"link": "link_https_para_acesso_o_bolix",
"billet_link":"link_https_para_acesso_o_bolix",
"pdf": {
"charge": "link_https_do_pdf_da_cobranca"
},
"expire_at": "2023-12-30",
"charge_id": numero_charge_id,
"status": "waiting",
"total": 8900,
"payment": "banking_billet"
}
}
{
"code": 200,
"data": {
"barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000",
"link": "link_https_para_acesso_o_bolix",
"billet_link":"link_https_para_acesso_o_bolix",
"pdf": {
"charge": "link_https_do_pdf_da_cobranca"
},
"expire_at": "2023-12-30",
"charge_id": numero_charge_id,
"status": "waiting",
"total": 8900,
"payment": "banking_billet"
}
}
Para retornar informações de uma transação (boleto ou cartão de crédito), você deve enviar uma requisição GET
para a rota /v1/charge/:id
.
GET /v1/charge/: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(200) do consumo.
{
"code": 200,
"data": {
"charge_id": 661176817,
"total": 1100,
"status": "waiting",
"custom_id": null,
"created_at": "2024-01-08 11:25:28",
"notification_url": null,
"items": [{
"name": "Product 1",
"value": 1000,
"amount": 1,
"marketplace": {
"repasses": [{
"percentage": 1000,
"payee_code": "84569721306548792010354876123456"
},
{
"percentage": 9000,
"payee_code": "36987410213546789104587410235689"
}
]
}
}],
"history": [{
"message": "Cobrança criada",
"created_at": "2024-01-08 11:25:28"
},
{
"message": "Pagamento via boleto aguardando confirmação",
"created_at": "2024-01-08 11:25:29"
},
{
"message": "Cobrança enviada para [email protected]",
"created_at": "2024-01-08 11:25:29"
}
],
"shippings": [{
"name": "Default Shipping Cost",
"value": 100,
"payee_code": "3804b62b6241d2ae9dd0896297d4ea74"
}],
"customer": {
"name": "Gorbadoc Oldbuck",
"cpf": "94271564656",
"birth": "1977-01-15",
"email": "[email protected]",
"phone_number": "5144916523"
},
"payment": {
"method": "banking_billet",
"created_at": "2024-01-08 11:25:28",
"message": null,
"banking_billet": {
"barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000",
"pix": {
"qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1",
"qrcode_image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmc vMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..."
},
"link": "link_https_para_acesso_o_bolix",
"billet_link": "link_https_para_acesso_o_bolix",
"pdf": {
"charge": "link_https_do_pdf_da_cobranca"
},
"expire_at": "2023-12-15"
}
}
}
}
Pagamento realizado como Pessoa Jurídica (PJ) O cliente associado à transação pode ser uma Pessoa Jurídica. Nesse caso, é necessário informar a Razão Social e o CNPJ da empresa pagadora no atributo juridical_person
.
Relação de todos os possíveis status de uma transação Todas as transações possuem um status que representa a "situação" dessa transação. É importante conhecer os possíveis status de uma transação na API para aplicar as devidas tratativas em seu sistema.
Callbacks (notificações) das transações da API para seu sistema As notificações permitem que você receba informações quando o status de uma transação for alterado, como quando um boleto for pago, por exemplo.
Confira aqui todos os detalhes sobre como implementar a sua URL de notificação.