Como posso configurar uma subconta por api?

Nesse manual você entenderá a estrutura dos processos bem como realizar as seguintes tarefas via API: 

• Criar uma subconta;
• Verificação de subconta;
• Configuração de contas e métodos de pagamentos para faturas (boleto, cartão de crédito e pix). 

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?” 

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? 

Diagrama de integração Modelo:

Criar subconta na Iugu: 

Para criar uma subconta na iugu, é necessário realizar um POST na API “Criar a subconta” clicando aqui. 

Endpoint: /v1/marketplace/create_account 

Ao criar uma subconta, você vai precisar definir as configurações de split para as outras contas, sejam elas mestre ou outras subcontas. Através da API você pode também definir as configurações para ambos os tipos. 

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 objeto Comissions.  

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 objeto Comissions, desta forma a iugu irá sempre splitar para essa conta mestre o valor definido em cada propriedade. 

Na prática, optar por uma combinação de tipos de comissão 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 comissions, 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: 

 

Modelo de response: 

 

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

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 clicando aqui. 

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

Modelo de request:

Modelo de retorno:

Atenção: 

• Só é possível criar uma subconta em ambiente produtivo iugu. 
• Os dados de retorno devem ser salvos no seu banco de dados, principalmente o user_token, que será utilizado como api_token para autenticar as chamadas da API nas subcontas. 
• As subcontas NÃO podem ser excluídas. 

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

Endpoint: /v1/accounts/account_id/request_verification 

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:

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:

Modelo de response:

Configurar o método de pagamento Pix para uma conta. 

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

Endpoint: /v1/marketplace/create_account 

Essa request é bem simples o método é PUT e no body deve ser informado true or false, na api_token deve ser usado o live-token da subconta. 

Modelo de request:

Modelo de response:

E é isso! Viu como é simples?  

Caso tenha qualquer dúvida, acesse nossos canais de suporte. 

 

 

Para saber mais informações e também para assistir ao vídeo com todos os passo a passo que produzimos sobre o conteúdo, assista ao vídeo a seguir: