📘

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 utilizar a funcionalidade de split para distribuir valores fixos para meus parceiros em suas respectivas subcontas. É possível configurar essa distribuição uma única vez, com a opção de realizar alterações quando necessário, ou será necessário definir essa distribuição individualmente para cada transação?"

A distribuição de valores, conhecida como Split de Pagamento, é predefinida por você e realizada automaticamente a cada recebimento. Existem várias formas de configurar essa operação: entre a conta principal (a sua) e as subcontas (contas dos seus parceiros, associados), ou apenas entre as subcontas.

Você pode definir se essa configuração será aplicada a todos os parceiros ou se precisará de uma configuração específica para cada um. Na prática, isso permite definir condições especiais para parceiros que apresentam maior volume de vendas.

Tudo isso é implementado de maneira simples e eficiente via API, com poucas chamadas POST, facilitando o processo sem complicações.

1. Criar Subconta

Utilize o endpoint Criar Subconta — POST v1/marketplace/create_account.

🚧

Apenas em produção

É possível Criar Subcontas apenas em ambiente de produção.

📘

account_id pode se tornar o nome da conta

Se o parâmetro name não for preenchido, o account_id gerado será utilizado como o nome da conta. Utilize o endpoint Configurar Conta — POST v1/accounts/configuration para alteração.

Request e Response exemplo

curl --request POST \
     --url 'https://api.iugu.com/v1/marketplace/create_account?api_token=<seu-api_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"name":"Subconta"}'

{
  "account_id": "49196DF60BC64B6EB42DEC9C5D81C2CC",
  "name": "Subconta",
  "live_api_token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA111111111111111111111111111111111",
  "test_api_token": "AAAAAAAAAAAAAAAAAAAAAA111111111111111111111111111111111AAAAAAAAA",
  "user_token": "111111111111111111111111111111111AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}

Armazene os tokens ⚠️

Esses dados são exibidos apenas neste retorno, então, certifique-se de armazená-los em segurança.

2. Enviar verificação de subconta

A verificação de uma subconta é obrigatória para realizar transações. Utilize o endpoint Enviar Verificação de Subconta — POST v1/accounts/{account_id}/request_verification. Esta chamada exige o user_token ao invés do api_token (etapa 1).

🚧

Não utilize dados fictícios

A verificação de conta exige dados reais para ser bem sucedida.

Preencha os parâmetros listados abaixo:

PATH PARAMS

BODY PARAMS

Objeto files

Arquivos (codificados em Base64 e com limite de 15 MB por arquivo) para KYC, como Foto do Documento de Identificação Pessoal, selfie etc.

Request e Response de exemplo:

curl --request POST \
     --url 'https://api.iugu.com/v1/accounts/account_id/request_verification?api_token=<seu-api_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "data": {
    "price_range": "Até R$ 100,00",
    "physical_products": false,
    "business_type": "Meu negócio",
    "person_type": "Pessoa Jurídica",
    "automatic_transfer": false,
    "cnpj": "89814893000112",
    "company_name": "Minha empresa",
    "street": "Av. das Nações Unidas",
    "number": "12495",
    "district": "Cidade Monções",
    "cep": "04578-000",
    "city": "São Paulo",
    "state": "SP",
    "telephone": "5511971111111",
    "resp_name": "Nome do Resp",
    "resp_cpf": "736.858.020-97",
    "estimated_revenue": "100.00",
    "bank": "Itaú",
    "bank_ag": "9999",
    "account_type": "Corrente",
    "bank_cc": "999999999-D"
  }
}
'

{
  "id": "FBB9275622CB4258A93A886C60B917EC",
  "data": {
    "price_range": "Até R$ 100,00",
    "physical_products": false,
    "business_type": "Meu negócio",
    "person_type": "Pessoa Jurídica",
    "automatic_transfer": false,
    "cep": "04578-000",
    "district": "Cidade Monções",
    "city": "São Paulo",
    "state": "SP",
    "street": "Av. das Nações Unidas",
    "number": "12495",
    "telephone": "5511971111111",
    "bank": "Itaú",
    "bank_ag": "9999",
    "account_type": "Corrente",
    "bank_cc": "999999999-D",
    "estimated_revenue": "100.00",
    "cnpj": "89814893000112",
    "company_name": "Minha empresa",
    "resp_name": "Nome do Resp",
    "resp_cpf": "736.858.020-97",
    "bank_ispb": "60701190"
  },
  "account_id": "FE2D01700CE3448C84B4DFD00049E1BC",
  "created_at": "2025-11-18T14:44:44-03:00"
}

Sequência de Chamadas

3. Configurar Subconta

Após criação da subconta, utilize o endpoint Configurar Conta — POST v1/accounts/configuration para alterações em suas configurações.

Ativar métodos de pagamento

Cartão de Crédito

Utilize o objeto credit_card e informe os seguintes parâmetros para:

Boleto Bancário

Utilize o objeto bank_slip e informe os seguintes parâmetros para:

Pix

Utilize o endpoint Configurar Pagamentos Pix — POST v1/payments/pix.

Com os métodos de pagamento que deseja devidamente ativados, continue com este artigo para configurar o Split de Pagamento.

Split de Pagamentos

Há uma série de formas de utilizar o Split Payment, independente de qual conta gerará a Fatura (Mestre ou Subconta). Consulte este artigo para saber mais.

Features complementares

Existem outros endpoints que permitem disponibilizar mais recursos ao seu parceiro. São eles:

Modificar Domicílio Bancário

Utilize o endpoint Adicionar Domicílio Bancário — POST v1/bank_verification para alterar a Conta Bancária que receberá os seus saques/transferências.

Dashboard

Utilize o endpoint Informações da Conta — GET v1/accounts/{id} para exibir dados como Saldo Disponível para Saque, Saldo de Recebíveis, etc.

Extrato Financeiro

Utilize o endpoint Extrato Financeiro — GET v1/accounts/financial para exibir dados que facilitam a conciliação.

Mais configurações

O endpoint Configurar Conta — v1/accounts/configuration conta com mais configurações do que as abordadas neste artigo. São elas:

📘

Antecipação de Recebíveis

Certifique-se de que a Antecipação de Recebíveis é um recurso disponível para utilização em sua conta. Para ativá-lo, contate nosso suporte.