Pular para o conteúdo principal

Split de pagamento

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í.


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 definida 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;

  • Se o total de repasses de um item for inferior a 100%, o restante será automaticamente repassado para a conta integradora;

  • Se o total de repasses de um item for superior a 100%, a transação não poderá ser gerada;

  • 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.

  • 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"  
"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

{
  "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ê"
    }
  }
}

Respostas

As respostas abaixo representam Sucesso do consumo.

{
  "code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
  "data": {
    "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000", // linha digitável do boleto
    "pix":{
      "qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1", // BRCode ou copia e cola
      "qrcode_image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmc vMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..." // QR Code imagem
    },
    "link": "link_https_para_acesso_o_bolix", // link responsivo do Bolix gerado
    "billet_link":"link_https_para_acesso_o_bolix", // link do Bolix gerado
    "pdf": {
      "charge": "link_https_do_pdf_da_cobranca" // link do PDF do Bolix
    },
    "expire_at": "2023-12-15", // data de vencimento do boleto no seguinte formato: 2022-12-15 (ou seja, equivale a 15/12/2022)
    "charge_id": numero_charge_id, // número da ID referente à transação gerada
    "status": "waiting", // forma de pagamento selecionada, aguardando a confirmação do pagamento ("waiting" equivale a "aguardando")
    "total": 5990, // valor, em centavos. Por exemplo: 5990 (equivale a R$ 59,90)
    "payment": "banking_billet" // forma de pagamento associada à esta transação ("banking_billet" equivale a "boleto bancário")
  }
}

Criação de transação Split de pagamento em Two Steps (Dois passos)​

  1. Crie a transação, informando conta(s) de repasse, o item/produto/serviço, valor, quantidade, etc;
  2. 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

{
  "items": [
    {
      "name": "Meu Produto",
      "value": 5990,
      "amount": 1,
      "marketplace": {
        "repasses": [
          {
            "payee_code": "payee_code1",
            "percentage": 2500
          },
          {
            "payee_code": "payee_code2",
            "percentage": 1500
          }
        ]
      }
    }
  ]
}

Respostas

As respostas abaixo representam Sucesso do consumo.

{
  "code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
  "data": {
    "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": 8900, // valor total da transação (em centavos, sendo 8900 = R$89,00)
    "custom_id": null, // identificador próprio opcional
    "created_at": "2021-06-01 14:58:46" // data e hora da criação da transação
  }
}

2. Associar à forma de pagamento via boleto​

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

{
  "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": {
    "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000", // linha digitável do boleto
    "pix":{
      "qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1", // BRCode ou copia e cola
      "qrcode_image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmc vMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..." // QR Code imagemm
    },
    "link": "link_https_para_acesso_o_bolix", // link responsivo do Bolix gerado
    "billet_link":"link_https_para_acesso_o_bolix", // link do Bolix gerado
    "pdf": {
      "charge": "link_https_do_pdf_da_cobranca" // link do PDF do Bolix
    },
    "expire_at": "2023-12-30", // data de vencimento do boleto no seguinte formato: 2022-12-15 (ou seja, equivale a 15/12/2022)
    "charge_id": numero_charge_id, // número da ID referente à transação gerada
    "status": "waiting", // forma de pagamento selecionada, aguardando a confirmação do pagamento ("waiting" equivale a "aguardando")
    "total": 8900, // valor, em centavos. Por exemplo: 5990 (equivale a R$ 59,90)
    "payment": "banking_billet" // forma de pagamento associada à esta transação ("banking_billet" equivale a "boleto bancário")
  }
}

Retornar informações de transação existente​

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.

Última atualização em