📘

O que você vai aprender com este artigo?

• Como criar uma subconta via Alia ou API
• Como verificar uma subconta para permitir transações
• Como configurar métodos de pagamento para a subconta
• Como desativar uma subconta de forma segura

Criar

Há duas formas de criar uma subconta na iugu:

1. Via Alia

1. Em sua Conta Mestre, acesse alia.iugu.com > Clique em Marketplace

2. No canto superior direito, clique em Nova
3. Preencha todos os campos obrigatórios
4. Defina se haverá ou não Split de Pagamento
5. Defina o nível de acesso
6. Clique em Salvar.

Saiba mais sobre como Criar Subconta via Alia.

2. Via API Criar Subconta

Utilize a rota POST /v1/marketplace/create_account. Não há parâmetros obrigatórios neste endpoint, porém, se o parâmetro name não for informado, o ID da Conta será utilizado por padrão.

Importante ⚠️

Não utilize números nem caracteres especiais no parâmetro name, pois impactam diretamente na ativação do método de pagamento Pix.

Requisição exemplo

curl --request POST \
     --url 'https://api.iugu.com/v1/marketplace/create_account?api_token=1ABC234567890DEF1ABC234567890DEF1ABC234567890DEF1ABC234567890DEF' \
     --header 'Request-Time: Timestemp da assinatura' \
     --header 'Signature: signature=<assinatura>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"name":"Subconta"}'

Retorno exemplo

{
  "account_id": "1ABC234567890DEF1ABC234567890DEF",
  "name": "Subconta A",
  "live_api_token": "1ABC234567890DEF1ABC234567890DEF1ABC234567890DEF1ABC234567890DEF",
  "test_api_token": "1ABC234567890DEF1ABC234567890DEF1ABC234567890DEF1ABC234567890DEF",
  "user_token": "1ABC234567890DEF1ABC234567890DEF1ABC234567890DEF1ABC234567890DEF",
  "commissions": null
}

Verificar (API)

🚧

Você só tem 24h! 🚨

Só é possível verificar uma subconta em até 24h após sua criação. Além disso, após a primeira chamada 200 OK, não será possível requisitá-la novamente.

Se deseja alterar o domicílio bancário, utilize o endpoint Adicionar Domicílio Bancário.

A verificação é uma etapa imprescindível para começar a transacionar em uma subconta. Para isso, utilize o endpoint Enviar Verificação de Subconta — POST /v1/accounts/{account_id}/request_verification.

Recipe:test_tube:

Clique na recipe abaixo e veja, na prática, a sequência de chamadas às APIs:

Informe os dados obrigatórios. São eles:

Objeto data

Dados cadastrais como Endereço, se Pessoa Física ou Jurídica etc.

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.

📘

Dica

Ao utilizar a referência da API Enviar Verificação de Subconta, o arquivo é codificado para Base64 automaticamente.

KYC,

A conta não será verificada após esta chamada, ela passará por uma análise primeiro e, se aprovada, terá seus status alterado de is_verified:false para true. O prazo para torná-la verified é de até 5 dias úteis.

✅

Seja notificado!

Utilize os gatilhos Status de Verificação de Conta iugu — referrals.verification e Mudança de Status de Documento — referrals.document_status_change.

Reenviar Documentação

Quando a documentação enviada é reprovada, o status será alterado de pending_manual_analisys para requested, acionando o gatilho referrals.document_status_change.

Retorno exemplo

{
  "data[status]": "requested",
  "data[account_id]": "481B0894128F41CFB67917EE5F0A5A08",
  "data[document_type]": "address_proof",
  "data[reason]": "Documento rasurado",
  "event": "referrals.document_status_change"
}

Para reenviá-lo, utilize o endpoint Reenviar Documentos para Verificar Conta iugu — /v1/account/documents. Saiba como com esta Recipe:

Alterar domicílio bancário

Só é possível verificar contas uma única vez. Portanto, caso precise alterar o Domicílio Bancário de uma conta já verificada, há duas formas:

Via Alia

Consulte o artigo Como cadastrar meu domicílio bancário.

Via API

Utilize o endpoint Adicionar Domicílio Bancário — POST /v1/bank_verification.

Configurar

Há inúmeras configurações que podem ser consideradas ou não. Siga abaixo algumas sugestões de configuração.

Ativar métodos de pagamento

Na iugu, há 3 métodos de pagamento, ative/desative o que desejar. Para todos, há duas formas:

1. Via Alia

Cartão de Crédito

1. Configurações > Cartão de Crédito
2. Marque a caixa de seleção Ativar
3. Clique em Salvar

Boleto Bancário

1. Configurações > Boleto Bancário
2. Marque a caixa de seleção Ativar
3. Clique em Salvar

Pix

1. Configurações > Pix
2. Marque a caixa de seleção Ativar
3. Clique em Salvar

2. Via API Configurar Conta

Recipe:test_tube:

Clique na recipe abaixo e veja, na prática, a sequência de chamadas às APIs:

Utilize o endpoint Configurar Conta — POST /v1/accounts/configuration, informe os parâmetros a seguir e faça a requisição:

Cartão de Crédito

{
  "credit_card": {
    "active": true
  }
}

Boleto Bancário

{
  "bank_slip": {
    "active": true
  }
}

Pix

Utilize o endpoint Ativar/desativar método Pix — POST /v1/payments/pix:

{
  "enable":true
}

Desativar Subconta

Se, por algum motivo, precisar desativar uma subconta, utilize o endpoint Desativar Subconta — POST /v1/marketplace/deactivate. Informe o account_id no URL (path) para a requisição.

Requisição exemplo

curl --request POST \
     --url 'https://api.iugu.com/v1/marketplace/deactivate?api_token=your_api_token' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "account_id": "9A15EA2E3A354B3CB6DFF5D055F2A594"
}
'

Importante ⚠️

Atente-se as informações importantes antes de requisitar este endpoint:

1. Ao requisitar este endpoint, todas as faturas, assinaturas e carnês pendentes serão cancelados e a conta terá o status unverified.
2. A conta não poderá ter saldo.
3. Não poderá reativá-la.
4. A requisição precisa ser feita utilizando o live_api_token da Conta Mestre.