Configurar subconta por API

📘

O que você irá aprender com esse artigo?

  • Criação de subcontas
  • Configuração da subconta
  • Verificação de conta
  • Configuração de cartão de crédito e boleto para uma conta
  • Configuração de Pix para uma conta

Case de uso

“Preciso usar o split para distribuir os valores para cada um dos meus parceiros em suas subcontas, sendo esse um valor fixo. Dessa maneira, consigo configurar isso uma única vez (ou quando precisar fazer alguma alteração) ou para cada transação terei que refazer essa distribuição?”

Diagrama de sequência

Na iugu, gostamos de dizer que tudo fica no automático, então essa distribuição de valores, o chamado split de pagamentos, é predefinido por você e realizado automaticamente toda vez que um recebimento cai. Mas há diferentes formas de configurar essa operação: entre a conta mestre (a sua) e as subcontas (contas dos seus parceiros, associados); ou entre as subcontas. E você define se essa configuração acontece para todos ou se precisa de uma configuração específica para cada parceiro. Na prática, isso serve para você definir, por exemplo, condições especiais para parceiros que vendem mais. Tudo isso é realizado via API de maneira bem simples e com poucas chamadas POST, para você não se perder em linhas de código.

Vamos entender melhor como funciona a estrutura dessas opções através da API?

Criar subconta na Iugu

Para criar uma subconta na iugu, é necessário realizar um POST na API Criar subconta.

Depois de criar a subconta será necessário realizar as configurações dela.

Configurar Subconta

Ao criar uma subconta, você vai precisar definir as configurações de métodos de pagamento, saque e split (se for usar split padrão por conta). Através da API, você pode definir as configurações de split para outras contas, sejam elas mestre ou outras subcontas.

Por exemplo: se você quer realizar a distribuição de uma venda do Vendedor X, você pode tanto apenas cobrar o seu comissionamento em cima do valor, ou pode, além disso, distribuir um valor para outras subcontas, como por exemplo para um serviço de frete, o que seria o split múltiplo.

Na iugu, é possível realizar esse procedimento por porcentagem, valor fixo(centavos) e pelo método de pagamento.

Split Subconta para Conta Mestre

Caso queira apenas realizar o split da subconta para a conta mestre, você deve preencher o array de Splits.

Se você precisa realizar um split para todos os métodos de pagamento com um valor, ou porcentagem fixa, indicamos que você preencha as propriedades cents e percents do array de objetos Splits e informe o identificador da conta Mestre, desta forma, a iugu irá sempre splitar para essa conta mestre o valor definido em cada propriedade.

Para saber o identificador da conta Mestre, veja aqui.

Na prática, optar por uma combinação de tipos de split serve para você, por exemplo, definir uma taxa de comissão por transação, definindo um valor fixo (cents), e um percentual (percents) sobre o valor total do recebimento.

Você ainda conta com a flexibilidade de poder definir valores específicos para cada método de pagamento (Boleto, Cartão de Crédito e Pix), seja ele por porcentagem, ou valor fixo. Para isso, basta preencher o array splits, configurando o cartão de crédito (credit_card), boleto bancário (bank_split), ou o Pix.

Para configurar com combinação do split por valor fixo e porcentagem, preencha os dois campos e mantenha como true a propriedade permit_aggregated.

Modelo de request

curl --location --request POST 'https://api.iugu.com/v1/marketplace/create_account' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=4ee94e4ee8b72f60ed03623bd362535f80b6646a-1645193529' \
--data-raw '{
    "name": "Nome da subconta",
    "splits": [
        {
            "recipient_account_id": "{{account_id}}",
            "percent": 15
        }
    ]
}'

Modelo de response

❗️

Token API

Ao realizar a requisição, deve ser armazenado em seu banco de dados as propriedades live_api_token (usado para chamadas no ambiente produtivo), teste_api_token (usado para chamadas em ambiente de teste), e o user_token (usado para realizar algumas requisições para a subconta, como por exemplo, enviar a verificação de subconta)

Split múltiplo

Na iugu, é possível realizar split múltiplo distribuindo valores entre mais de duas contas, sejam elas subcontas ou contas mestre.

Para realizar a configuração do split múltiplo, é necessário preencher o array splits, onde cada novo objeto será um conta.

Acompanhe abaixo:

A propriedade recipient_account_id representa a conta para qual será feito o split. Para mais informações de como consultar esse id, basta acessar o artigo ID da conta e tokens de API de teste e de produção.

Assim como o objeto comissions , no array splits é possível configurar o split por porcentagem, centavos, quantidade de parcelas, métodos de pagamento ou também ter um split cobrando um valor fixo mais um determinado percentual.

Modelo de request

curl --location --request POST 'https://api.iugu.com/v1/marketplace/create_account' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=c20578845af8b7a7dcc49590f743511096fa1ba9-1626446741' \
--data-raw '{
    "splits": [
        {
            "recipient_account_id": "{{account_id}}",
            "cents": 1000,
            "percent": 2,
            "permit_aggregated": true
        }
    ],
    "name": "Iugu"
}'

Modelo de response

❗️

Atenção

  • Só é possível criar uma subconta em ambiente produtivo iugu.
  • As subcontas NÃO podem ser excluídas.

Além das configurações de split, acesse a API para ver como ligar/desligar transferência automática, antecipação automática, descontos etc. Todas estas estão disponíveis na API de Configurar Conta.

Splitter

O splitter usa basicamente a funcionalidade de marketplace parar operar, porém, com a diferença de fazer uma carga de dinheiro em sua conta iugu (pagamento de um boleto gerado por ele mesmo) e transferindo o dinheiro para uma ou mais subcontas.

A API mais importante do Splitter é a que permite a transferência de valores entre a conta mestre e a subconta, fazendo de fato o split. Os detalhes dessa chamada podem ser encontrados em Transferir Valor.

Enviar verificação de subconta

Nessa request, você pode solicitar a verificação dos dados de uma subconta e precisará ter as seguintes informações:
• O valor máximo para venda;
• Informar se serão produtos físicos;
• Descrição do negócio;
• O tipo de pessoa responsável pela subconta (física ou jurídica);
• Inserir informações do cliente como CNPJ, CPF, nome da pessoa, ou empresa, endereço, cep, bairro, telefone, banco, agência e tipo de conta;
• E confirmar se o saque será automático.

Para realizar a requisição, é necessário realizar um POST na API Enviar verificação de subconta.

Para essa chamada, deve ser alterado a api_token, pela user_token dessa subconta iugu. A propriedade user_token é retornada na api Criar Subconta da iugu. Além disso, deve ser informado o account_id na url da requisição. Essa propriedade também é retornada na API.

Para mais informações sobre qual o tipo de cada campo e como enviar eles na requisição, acesse o link da documentação aqui.

Modelo de request

curl --location --request POST 'https://api.iugu.com/v1/accounts/{{subconta_id}}/request_verification' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=c20578845af8b7a7dcc49590f743511096fa1ba9-1626446741' \
--data-raw '{
     "data": {
          "physical_products": false,
          "business_type": "teste",
          "person_type": "Pessoa Física",
          "automatic_transfer": true,
          "cep": "09550000",
          "city": "São caetano do sul",
          "district*": "Barcelona",
          "state": "SP",
          "telephone": "11951701021",
          "resp_cpf": "551.340.520-26",
          "price_range": "10000000",
          "bank_ag": "1500",
          "bank_cc": "0076857-P",
          "account_type": "Corrente",
          "bank": "Bradesco",
          "address": "Rua Conselheiro Lafayetti",
          "name": "Funcionário Iugu",
          "cpf": "551.340.520-26"
     }
}'

Modelo de response

Configurar cartão de crédito e boleto para uma conta

Essa requisição possibilita, de forma geral, a configuração dos parâmetros de sua conta para cartão de crédito e boleto bancário como métodos de pagamento.

Para realizar essa requisição, é necessário usar o user_token no lugar da api_key na url.

O que é possível configurar?
• Novas configurações de splits
• Saque automático
• Multas
• Juros de mora
• Valor de multa em porcentagem
• Antecipação automática
• Habilitar o boleto bancário e definir seus dias para vencimento
• Habilitar o cartão de crédito, definir o soft descriptor, parcelamento e transação em duas etapas
• Desconto por pagamento antecipado
• Desabilitar o saque da subconta
• Configurar valor de reserva para saque

Modelo de request

curl --location --request POST 'https://api.iugu.com/v1/accounts/configuration' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=0061e0ce76c9748e57cfd03b25563473a0fe496a-1626699286' \
--data-raw '{
     "bank_slip": {
          "active": true
     },
     "credit_card": {
          "active": true,
          "soft_descriptor":"teste iugu"
     },
     "disabled_withdraw": true
}'

Modelo de response

Configurar Pix para uma conta

Para realizar essa configuração, a conta precisa estar verificada. Isso significa que você precisa realizar a request Enviar verificação de subconta. Caso contrário, será retornado o status http 401 com a mensagem de Unauthorized.

A requisição de configuração do PIX é bem simples. No método deve-se colocar PUT e no body deve ser informado true ou false. Na api_token deve ser usado o live-token da subconta.

Modelo de request

curl --location --request PUT 'https://api.iugu.com/v1/payments/pix' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=0061e0ce76c9748e57cfd03b25563473a0fe496a-1626699286' \
--data-raw '{
    "enable": true
}'

Modelo de response

Modificar domicílio bancário

Tela que permite ao cliente que altere seus dados bancários para recebimento de seus valores. Simples formulário para envio posterior de chamada na API de Adicionar Domicílio Bancário.

Tela de dashboard

Exibe as informações da subconta iugu, como saldos e situação de verificação de conta. Não precisa ser uma tela somente para isso mas as informações são buscadas através da API de Informações da Conta.

Extrato Financeiro

Este pode ser utilizado para conciliação e suas informações são encontradas na API de Extrato Financeiro.

🚧

Transações

Idealmente, as transações devem ser feitas diretamente nas subcontas. O comissionamento pode ser feito de duas formas:

  • Automático (configurado com a API de configuração);
  • Com transferências via API utilizando a chamada de Transferir Valor.