Contas Virtuais - Blockradar

Em resumo
As Contas Virtuais permitem que seus clientes recebam pagamentos em fiat através de transferências bancárias tradicionais, que são automaticamente convertidas em stablecoins na blockchain. Você pode criar múltiplas contas virtuais por carteira ou endereço, com suporte para rotulagem, paginação e regeneração de contas.

Pré-requisitos

Antes de usar a API de Contas Virtuais, certifique-se de ter:

Chave API

Obtenha sua chave API no Painel da Blockradar. Navegue até Developers para gerar uma.

Carteira Criada

Crie uma carteira via API Criar Carteira ou painel. Você precisará do walletId para operações de contas virtuais.

Conformidade Aprovada

Complete o Formulário de Due Diligence (veja Requisitos de Conformidade abaixo).

Recurso Habilitado

Solicite a ativação do recurso de contas virtuais após aprovação de conformidade. Contate [email protected] ou use o chat ao vivo no painel.

Ambiente Mainnet

Contas virtuais estão disponíveis apenas na MAINNET. Ambientes de testnet não suportam operações de contas virtuais.

Suporte a Stablecoin

Certifique-se de que seu plano de conta inclua acesso a stablecoin. Atualize em Painel → Configurações → Assinatura se necessário.

Como Funciona

Criação de Conta

Crie contas virtuais vinculadas a carteiras mestras ou endereços filhos com informações do cliente.

Recebimento de Pagamento

Clientes enviam pagamentos em fiat para a conta virtual usando transferências bancárias tradicionais.

Financiamento Automático

Os pagamentos acionam automaticamente a cunhagem do equivalente em stablecoin.

Gerenciamento de Fundos

Stablecoins cunhadas são transferidas para a carteira ou endereço vinculado para uso imediato.

Fluxo de Financiamento Automático

Todas as contas virtuais usam AUTO_FUNDING, que converte automaticamente fiat para stablecoin. Quando um cliente envia moeda fiat para uma conta virtual:

1. Recebimento de Pagamento

O pagamento é recebido na conta virtual através de transferência bancária tradicional. Um webhook deposit.processing é acionado nesta etapa.

2. Cunhagem Automática

O sistema cunha automaticamente o equivalente em stablecoin na blockchain.

3. Transferência na Blockchain

A stablecoin cunhada é transferida para a carteira ou endereço vinculado da conta virtual. Um webhook deposit.success é acionado após conclusão bem-sucedida.

Requisitos de Conformidade

Antes de acessar contas virtuais, complete o processo de integração de conformidade.

Documentos Necessários

Certificado de Incorporação
ID para Diretores/Acionistas
Documento de Política KYC

Enviar Aplicação

Complete o Formulário de Due Diligence com os detalhes da sua empresa, informações de conformidade e upload de documentos.

Moeda Suportada

Fiat: NGN (Naira Nigeriana) - Transferências bancárias tradicionais
Stablecoin: cNGN - Cunhada automaticamente na blockchain

Endpoints da API

Abaixo estão os principais endpoints da API para operações de Contas Virtuais:

Endpoints da Carteira Mestra

POST /wallets//virtual-accounts – Criar uma conta virtual para uma carteira mestra
GET /wallets//virtual-accounts – Listar todas as contas virtuais (paginado)
GET /wallets//virtual-accounts/ – Recuperar uma conta virtual específica
GET /wallets//virtual-accounts//transactions – Obter transações de uma conta virtual
PATCH /wallets//virtual-accounts/ – Atualizar status da conta virtual
POST /wallets//virtual-accounts//regenerate – Regenerar uma conta virtual

Endpoints de Endereço Filho

POST /wallets//addresses//virtual-accounts – Criar uma conta virtual para um endereço filho
GET /wallets//addresses//virtual-accounts – Listar todas as contas virtuais (paginado)
GET /wallets//addresses//virtual-accounts/ – Recuperar uma conta virtual específica
GET /wallets//addresses//virtual-accounts//transactions – Obter transações de uma conta virtual
PATCH /wallets//addresses//virtual-accounts/ – Atualizar status da conta virtual
POST /wallets//addresses//virtual-accounts//regenerate – Regenerar uma conta virtual

Criando Contas Virtuais

Você pode criar contas virtuais tanto para carteiras mestras quanto para endereços filhos, dependendo do seu caso de uso. Use a API de Criar Conta Virtual para carteiras mestras ou a API de Criar Conta Virtual para endereços filhos.

Parâmetros de Solicitação

Parâmetro	Tipo	Obrigatório	Descrição
`firstname`	string	Sim	Primeiro nome do cliente (máx. 29 caracteres)
`lastname`	string	Sim	Sobrenome do cliente (máx. 29 caracteres)
`email`	string	Sim	Endereço de e-mail do cliente (deve ser único por negócio)
`phone`	string	Não	Número de telefone do cliente no formato: +234XXXXXXXXXX
`label`	string	Não	Rótulo personalizado para identificar esta conta virtual (máx. 100 caracteres)

Exemplo de Solicitação

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "phone": "+2348161846125",
  "label": "Conta Principal"
}

Exemplo de Resposta

{
  "data": {
    "id": "8180309e-1ead-4a72-a013-b5674600ce4c",
    "accountName": "John Doe",
    "accountNumber": "9018927611",
    "bankName": "Polaris Bank",
    "bankCode": "076",
    "currency": "NGN",
    "type": "AUTO_FUNDING",
    "isActive": true,
    "status": "ACTIVE",
    "label": "Conta Principal",
    "reference": "20",
    "customer": {
      "id": "caa17eb8-4da8-45b4-a866-81dd0a1df613",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+2348161846125",
      "status": "ACTIVE",
      "network": "mainnet"
    },
    "wallet": {
      "id": "35e964a6-436a-424f-bf3a-618cc060feea",
      "name": "Base Wallet",
      "address": "0xD8582C57E56Ef45f9fe82870aDF63d9baB89e1F7"
    },
    "createdAt": "2025-11-06T18:30:34.286Z",
    "updatedAt": "2025-11-06T18:30:34.286Z"
  },
  "message": "Virtual account created successfully",
  "statusCode": 201
}

Múltiplas Contas Virtuais

Você pode criar múltiplas contas virtuais por carteira ou endereço filho. Isso é útil quando:

Um cliente precisa de contas separadas para diferentes propósitos (ex.: poupança, pagamentos)
Você quer rastrear pagamentos de diferentes fontes separadamente
A conta virtual existente de um cliente precisa ser substituída mantendo o histórico

Apenas uma conta virtual por e-mail de cliente pode estar ativa por vez. Criar uma nova conta virtual para o mesmo e-mail exigirá desativar a existente primeiro, ou usar o endpoint de regeneração.

Listando Contas Virtuais

O endpoint de listagem retorna uma lista paginada de todas as contas virtuais. Use parâmetros de consulta para filtrar e paginar resultados.

Parâmetros de Consulta

Parâmetro	Tipo	Descrição
`page`	number	Número da página (padrão: 1)
`limit`	number	Resultados por página (padrão: 10)
`isActive`	boolean	Filtrar por status ativo (`true` ou `false`)

Exemplo de Resposta

{
  "message": "Virtual accounts retrieved successfully",
  "statusCode": 200,
  "data": [
    {
      "id": "597ef702-f096-4f8a-a542-29e8757ba208",
      "reference": "172",
      "accountNumber": "9012271961",
      "accountName": "John Doe",
      "bankName": "Polaris Bank",
      "bankCode": "076",
      "currency": "NGN",
      "isActive": true,
      "status": "ACTIVE",
      "type": "AUTO_FUNDING",
      "label": null,
      "createdAt": "2025-01-21T22:15:55.746Z",
      "updatedAt": "2025-01-21T22:15:55.746Z",
      "customer": {
        "id": "3082e278-557a-44f0-9205-c2639560cd5a",
        "name": "John Doe",
        "email": "[email protected]",
        "phone": "+2346112768485",
        "status": "ACTIVE",
        "network": "mainnet"
      },
      "wallet": {
        "id": "35e964a6-436a-424f-bf3a-618cc060feea",
        "name": "Base Wallet",
        "address": "0xD8582C57E56Ef45f9fe82870aDF63d9baB89e1F7"
      },
      "address": null
    }
  ],
  "meta": {
    "totalItems": 4,
    "itemCount": 4,
    "itemsPerPage": 10,
    "totalPages": 1,
    "currentPage": 1
  }
}

Recuperando uma Conta Virtual

Para recuperar uma conta virtual específica por ID, use a API de Obter Conta Virtual para carteiras mestras ou a API de Obter Conta Virtual para endereços filhos.

Exemplo de Resposta

{
  "message": "Virtual account retrieved successfully",
  "statusCode": 200,
  "data": {
    "id": "597ef702-f096-4f8a-a542-29e8757ba208",
    "reference": "172",
    "accountNumber": "9012271961",
    "accountName": "John Doe",
    "bankName": "Polaris Bank",
    "bankCode": "076",
    "currency": "NGN",
    "isActive": true,
    "status": "ACTIVE",
    "type": "AUTO_FUNDING",
    "label": "Conta Principal",
    "createdAt": "2025-01-21T22:15:55.746Z",
    "updatedAt": "2025-01-21T22:15:55.746Z",
    "customer": {
      "id": "3082e278-557a-44f0-9205-c2639560cd5a",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+2348161846125",
      "status": "ACTIVE",
      "network": "mainnet"
    },
    "wallet": {
      "id": "35e964a6-436a-424f-bf3a-618cc060feea",
      "name": "Base Wallet",
      "address": "0xD8582C57E56Ef45f9fe82870aDF63d9baB89e1F7"
    },
    "address": null
  }
}

Transações de Conta Virtual

Você pode recuperar todas as transações associadas a uma conta virtual específica usando o endpoint de transações.

Parâmetros de Consulta

Parâmetro	Tipo	Descrição
`page`	number	Número da página (padrão: 1)
`limit`	number	Resultados por página (padrão: 10)

Exemplo de Resposta

{
  "message": "Virtual account transactions retrieved successfully",
  "statusCode": 200,
  "data": [
    {
      "id": "ad3ce9a3-3e1c-43dc-bb7f-2c570fc7bfdc",
      "reference": "auto-funding-09026725110701402449700167083590131815",
      "senderAddress": "0xD2b6be31932E0294F2ebD14a008C3f1E05B47BC4",
      "recipientAddress": "0xbaD4E4B5e6660AcD138F776a992b566e8Bf3bb15",
      "amount": "50.0",
      "amountPaid": "50.0",
      "amountUSD": "0.03382",
      "currency": "NGN",
      "status": "SUCCESS",
      "type": "DEPOSIT",
      "note": "Auto funding of 50.0 cNGN to 0xbaD4E4B5e6660AcD138F776a992b566e8Bf3bb15",
      "network": "mainnet",
      "metadata": {
        "autoFunding": {
          "narration": "NIBSS:9018927611:SULEIMAN, ABDULFATAI:Sending:090267251107014024497001670835",
          "sessionId": "09026725110701402449700167083590131815",
          "senderBankName": "KUDA MFB",
          "senderAccountName": "SULEIMAN, ABDULFATAI"
        }
      },
      "createdAt": "2025-01-22T22:29:28.679Z",
      "asset": {
        "name": "cNGN",
        "symbol": "cNGN",
        "currency": "NGN"
      },
      "blockchain": {
        "name": "base",
        "slug": "base"
      }
    }
  ],
  "meta": {
    "totalItems": 1,
    "itemCount": 1,
    "itemsPerPage": 10,
    "totalPages": 1,
    "currentPage": 1
  }
}

O campo metadata.autoFunding contém detalhes sobre a origem do pagamento em fiat, incluindo o nome do banco do remetente, nome da conta e a narração da transferência bancária.

Regenerando Contas Virtuais

O endpoint de regeneração permite criar uma nova conta virtual para um cliente enquanto desativa a existente. Isso é útil quando:

Os detalhes bancários de um cliente precisam mudar
A conta virtual foi comprometida
Você precisa migrar um cliente para um banco diferente

Parâmetros de Regeneração

Parâmetro	Tipo	Obrigatório	Descrição
`firstname`	string	Sim	Primeiro nome do cliente (máx. 29 caracteres)
`lastname`	string	Sim	Sobrenome do cliente (máx. 29 caracteres)
`email`	string	Sim	Endereço de e-mail do cliente
`phone`	string	Não	Número de telefone do cliente no formato: +234XXXXXXXXXX
`reason`	string	Sim	Motivo para regenerar a conta virtual
`label`	string	Não	Rótulo personalizado para a nova conta virtual

Exemplo de Solicitação

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "phone": "+2348161846125",
  "reason": "Cliente solicitou novo número de conta",
  "label": "Nova Conta Principal"
}

A operação de regeneração desativará a conta virtual existente e criará uma nova. O histórico de transações da conta original é preservado e ainda pode ser consultado.

Atualizando Contas Virtuais

Você pode ativar ou desativar contas virtuais para controlar o comportamento de financiamento automático. Use a API de Atualizar Conta Virtual para carteiras mestras ou a API de Atualizar Conta Virtual para endereços filhos.

Comportamento de Financiamento Automático

Contas ativas: Pagamentos recebidos acionam cunhagem automática de stablecoin
Contas inativas: Pagamentos são recebidos mas o financiamento automático está desabilitado

Parâmetros de Atualização

Parâmetro	Tipo	Obrigatório	Descrição
`isActive`	boolean	Sim	`true` para ativar, `false` para desativar

Exemplo de Solicitação

{
  "isActive": false
}

Exemplo de Resposta

{
  "message": "Virtual account updated successfully",
  "statusCode": 200,
  "data": {
    "id": "597ef702-f096-4f8a-a542-29e8757ba208",
    "accountNumber": "9012271961",
    "accountName": "John Doe",
    "bankName": "Polaris Bank",
    "isActive": false,
    "status": "INACTIVE",
    "type": "AUTO_FUNDING",
    "label": "Conta Principal"
  }
}

Quando uma conta virtual é desativada (isActive: false), os pagamentos ainda podem ser recebidos mas o processo automático de cunhagem e transferência de stablecoin é desabilitado. Você pode reativar a conta a qualquer momento para reabilitar o financiamento automático.

Webhooks

As contas virtuais acionam eventos de webhook quando os pagamentos são recebidos e processados. Você receberá notificações de webhook em cada etapa do fluxo de processamento de pagamento.

Eventos de Webhook

Quando um cliente envia pagamento em fiat para uma conta virtual:

deposit.processing - Acionado imediatamente quando o pagamento em fiat é recebido na conta virtual. Isso indica que o pagamento foi detectado e o processo de cunhagem está prestes a começar.
deposit.success - Acionado quando a stablecoin foi cunhada e transferida com sucesso para a carteira ou endereço vinculado. Isso confirma que todo o processo de financiamento automático está completo.
deposit.failed - Acionado se o processo de cunhagem ou transferência falhar em qualquer ponto.
deposit.cancelled - Acionado se a transação for cancelada antes da conclusão.

Exemplo de Payload do Webhook

{
  "event": "deposit.success",
  "data": {
    "id": "ad3ce9a3-3e1c-43dc-bb7f-2c570fc7bfdc",
    "reference": "auto-funding-09026725110701402449700167083590131815",
    "amount": "50.0",
    "currency": "NGN",
    "status": "SUCCESS",
    "type": "DEPOSIT",
    "network": "mainnet",
    "metadata": {
      "autoFunding": {
        "sessionId": "09026725110701402449700167083590131815",
        "senderBankName": "KUDA MFB",
        "senderAccountName": "SULEIMAN, ABDULFATAI"
      }
    },
    "virtualAccount": {
      "id": "597ef702-f096-4f8a-a542-29e8757ba208",
      "accountNumber": "9012271961",
      "bankName": "Polaris Bank"
    },
    "wallet": {
      "id": "35e964a6-436a-424f-bf3a-618cc060feea",
      "name": "Base Wallet"
    }
  }
}

Webhooks são acionados apenas para contas virtuais ativas (isActive: true). Se uma conta for desativada, os pagamentos ainda podem ser recebidos, mas eventos de webhook não serão enviados até que a conta seja reativada.

Para mais informações sobre configuração de webhook, estrutura de payload e tratamento de eventos, veja a documentação de Webhooks.

Casos de Uso

Pagamentos de E-commerce

Crie contas virtuais para clientes receberem pagamentos por produtos ou serviços. A conversão automática para stablecoins permite integração perfeita com seu sistema de pagamento baseado em blockchain.

Serviços de Assinatura

Vincule contas virtuais a assinaturas de clientes, permitindo pagamentos recorrentes através de transferências bancárias tradicionais que são automaticamente convertidas em stablecoins.

Transações de Marketplace

Habilite transações peer-to-peer onde os clientes podem enviar pagamentos em fiat que são instantaneamente convertidos em stablecoins e creditados em sua carteira.

Serviços de Remessa

Forneça aos clientes contas virtuais para receber remessas em NGN, que são automaticamente convertidas em stablecoins para fáceis transferências transfronteiriças.

Próximos Passos

Uma vez que cNGN esteja na sua carteira:

Swap - Converta cNGN para USDT, USDC ou outras stablecoins sob demanda
Auto-Settlement - Converta automaticamente cNGN para USDT/USDC em cada depósito

Melhores Práticas

Gerenciamento de Contas

Use rótulos descritivos: Adicione rótulos significativos às contas virtuais (ex.: “Poupança”, “Pagamentos”) para fácil identificação
Endereços de e-mail únicos: Certifique-se de que cada cliente tenha um endereço de e-mail único por conta ativa
Formato de número de telefone: Sempre use o formato correto (+234XXXXXXXXXX) para números de telefone nigerianos
Ativação de conta: Ative contas apenas quando estiver pronto para processar pagamentos
Monitore o status da conta: Verifique regularmente o status da conta e trate contas inativas apropriadamente
Documente motivos de regeneração: Sempre forneça motivos claros ao regenerar contas para fins de auditoria

Múltiplas Contas

Planeje sua estrutura de contas: Decida antecipadamente quantas contas cada cliente pode precisar
Use rótulos consistentemente: Estabeleça uma convenção de nomenclatura para rótulos em sua aplicação
Rastreie histórico de contas: Ao regenerar, mantenha referências aos IDs de contas anteriores para reconciliação de transações

Segurança

Verificação de cliente: Verifique as informações do cliente antes de criar contas virtuais
Validação de conta: Valide os detalhes da conta antes de processar pagamentos
Controle de acesso: Implemente controles de acesso adequados para gerenciamento de contas virtuais

Tratamento de Erros

A API retorna códigos de status HTTP padrão e respostas de erro. Os erros comuns incluem:

Código de Status	Erro	Descrição
`400`	Bad Request	Parâmetros de solicitação inválidos (ex.: formato de e-mail inválido, nome excede 29 caracteres)
`401`	Unauthorized	Chave API ausente ou inválida
`404`	Not Found	Conta virtual ou carteira não encontrada
`409`	Conflict	O e-mail já existe para uma conta virtual ativa
`422`	Unprocessable Entity	Validação falhou (ex.: campos obrigatórios ausentes)

Exemplo de Resposta de Erro

{
  "message": "A virtual account with this email already exists",
  "statusCode": 409,
  "error": "Conflict"
}

Quando você receber um erro 409 por e-mail duplicado, desative primeiro a conta virtual existente ou use o endpoint de regeneração para criar uma nova conta para o mesmo cliente.

Suporte

E-mail: [email protected]
Chat ao vivo: Disponível no painel
Referência da API: API de Contas Virtuais

Precisa de suporte para stablecoins ou moedas adicionais? Contate [email protected].

Começar

Essenciais

​Pré-requisitos

​Como Funciona

Criação de Conta

Recebimento de Pagamento

Financiamento Automático

Gerenciamento de Fundos

​Fluxo de Financiamento Automático

​1. Recebimento de Pagamento

​2. Cunhagem Automática

​3. Transferência na Blockchain

​Requisitos de Conformidade

​Documentos Necessários

​Enviar Aplicação

​Moeda Suportada

​Endpoints da API

​Endpoints da Carteira Mestra

​Endpoints de Endereço Filho

​Criando Contas Virtuais

​Parâmetros de Solicitação

​Exemplo de Solicitação

​Exemplo de Resposta

​Múltiplas Contas Virtuais

​Listando Contas Virtuais

​Parâmetros de Consulta

​Exemplo de Resposta

​Recuperando uma Conta Virtual

​Exemplo de Resposta

​Transações de Conta Virtual

​Parâmetros de Consulta

​Exemplo de Resposta

​Regenerando Contas Virtuais

​Parâmetros de Regeneração

​Exemplo de Solicitação

​Atualizando Contas Virtuais

​Comportamento de Financiamento Automático

​Parâmetros de Atualização

​Exemplo de Solicitação

​Exemplo de Resposta

​Webhooks

​Eventos de Webhook

​Exemplo de Payload do Webhook

​Casos de Uso

​Pagamentos de E-commerce

​Serviços de Assinatura

​Transações de Marketplace

​Serviços de Remessa

​Próximos Passos

​Melhores Práticas

​Gerenciamento de Contas

​Múltiplas Contas

​Segurança

​Tratamento de Erros

​Exemplo de Resposta de Erro

​Suporte

Pré-requisitos

Como Funciona

Fluxo de Financiamento Automático

1. Recebimento de Pagamento

2. Cunhagem Automática

3. Transferência na Blockchain

Requisitos de Conformidade

Documentos Necessários

Enviar Aplicação

Moeda Suportada

Endpoints da API

Endpoints da Carteira Mestra

Endpoints de Endereço Filho

Criando Contas Virtuais

Parâmetros de Solicitação

Exemplo de Solicitação

Exemplo de Resposta

Múltiplas Contas Virtuais

Listando Contas Virtuais

Parâmetros de Consulta

Exemplo de Resposta

Recuperando uma Conta Virtual

Exemplo de Resposta

Transações de Conta Virtual

Parâmetros de Consulta

Exemplo de Resposta

Regenerando Contas Virtuais

Parâmetros de Regeneração

Exemplo de Solicitação

Atualizando Contas Virtuais

Comportamento de Financiamento Automático

Parâmetros de Atualização

Exemplo de Solicitação

Exemplo de Resposta

Webhooks

Eventos de Webhook

Exemplo de Payload do Webhook

Casos de Uso

Pagamentos de E-commerce

Serviços de Assinatura

Transações de Marketplace

Serviços de Remessa

Próximos Passos

Melhores Práticas

Gerenciamento de Contas

Múltiplas Contas

Segurança

Tratamento de Erros

Exemplo de Resposta de Erro

Suporte